sim/README-HACKING

   1 This is a loose collection of notes for people hacking on simulators.
   2 If this document gets big enough it can be prettied it up then.
   3
   4 Contents
   5
   6 - The "common" directory
   7 - Common Makefile Support
   8 - Generating "configure" files
   9 \f
  10 The "common" directory
  11 ======================
  12
  13 The common directory contains:
  14
  15 - common documentation files (e.g. run.1, and maybe in time .texi files)
  16 - common source files (e.g. run.c)
  17 - common Makefile fragment and configury (e.g. Make-common.in, aclocal.m4).
  18
  19 In addition "common" contains portions of the system call support
  20 (e.g. callback.c, nltvals.def).
  21
  22 Even though no files are built in this directory, it is still configured
  23 so support for regenerating nltvals.def is present.
  24 \f
  25 Common Makefile Support
  26 =======================
  27
  28 A common configuration framework is available for simulators that want
  29 to use it.  The common framework exists to remove a lot of duplication
  30 in configure.in and Makefile.in, and it also provides a foundation for
  31 enhancing the simulators uniformly (e.g. the more they share in common
  32 the easier a feature added to one is added to all).
  33
  34 The configure.in of a simulator using the common framework should look like:
  35
  36 --- snip ---
  37 dnl Process this file with autoconf to produce a configure script.
  38 sinclude(../common/aclocal.m4)
  39 AC_PREREQ(2.5)dnl
  40 AC_INIT(Makefile.in)
  41
  42 SIM_AC_COMMON
  43
  44 ... target specific additions ...
  45
  46 SIM_AC_OUTPUT
  47 --- snip ---
  48
  49 SIM_AC_COMMON:
  50
  51 - invokes the autoconf macros most often used by the simulators
  52 - defines --enable/--with options usable by all simulators
  53 - initializes sim_link_files/sim_link_links as the set of symbolic links
  54   to set up
  55
  56 SIM_AC_OUTPUT:
  57
  58 - creates the symbolic links defined in sim_link_{files,links}
  59 - creates config.h
  60 - creates the Makefile
  61
  62 The Makefile.in of a simulator using the common framework should look like:
  63
  64 --- snip ---
  65 # Makefile for blah ...
  66 # Copyright blah ...
  67
  68 ## COMMON_PRE_CONFIG_FRAG
  69
  70 # These variables are given default values in COMMON_PRE_CONFIG_FRAG.
  71 # We override the ones we need to here.
  72 # Not all of these need to be mentioned, only the necessary ones.
  73
  74 # List of object files, less common parts.
  75 SIM_OBJS =
  76 # List of flags to always pass to $(CC).
  77 SIM_EXTRA_CFLAGS =
  78 # List of extra libraries to link with.
  79 SIM_EXTRA_LIBS =
  80 # List of extra program dependencies.
  81 SIM_EXTRA_LIBDEPS =
  82 # List of main object files for `run'.
  83 SIM_RUN_OBJS = run.o
  84 # Dependency of `all' to build any extra files.
  85 SIM_EXTRA_ALL =
  86 # Dependency of `install' to install any extra files.
  87 SIM_EXTRA_INSTALL =
  88 # Dependency of `clean' to clean any extra files.
  89 SIM_EXTRA_CLEAN =
  90
  91 ## COMMON_POST_CONFIG_FRAG
  92
  93 # Rules need to build $(SIM_OBJS), plus whatever else the target wants.
  94
  95 ... target specific rules ...
  96 --- snip ---
  97
  98 COMMON_{PRE,POST}_CONFIG_FRAG are markers for SIM_AC_OUTPUT to tell it
  99 where to insert the two pieces of common/Make-common.in.
 100 The resulting Makefile is created by doing autoconf substitions on
 101 both the target's Makefile.in and Make-common.in, and inserting
 102 the two pieces of Make-common.in into the target's Makefile.in at
 103 COMMON_{PRE,POST}_CONFIG_FRAG.
 104 \f
 105 Generating "configure" files
 106 ============================
 107
 108 For target's using the common framework, "configure" can be generated
 109 by running autoconf.  This works because configure.in contains
 110 "sinclude(../common/aclocal.m4)".
 111
 112 To regenerate the configure files for all targets using the common framework:
 113
 114         $  cd devo/sim
 115         $  make -f Makefile.in autoconf-common
 116
 117 To add a change-log entry to the ChangeLog file for each updated
 118 directory (WARNING - check the modified new-ChangeLog files before
 119 renaming):
 120
 121         $  make -f Makefile.in autoconf-changelog
 122         $  more */new-ChangeLog
 123         $  make -f Makefile.in autoconf-install
 124
 125 In a similar vein, both the configure and config.in files can be
 126 updated using the sequence:
 127
 128         $  cd devo/sim
 129         $  make -f Makefile.in autoheader-common
 130         $  make -f Makefile.in autoheader-changelog
 131         $  more */new-ChangeLog
 132         $  make -f Makefile.in autoheader-install
 133