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 up then.
   3
   4 Contents
   5
   6 - The "common" directory
   7 - Common Makefile Support
   8 - TAGS support
   9 - Generating "configure" files
  10 - tconfig.in
  11 \f
  12 The "common" directory
  13 ======================
  14
  15 The common directory contains:
  16
  17 - common documentation files (e.g. run.1, and maybe in time .texi files)
  18 - common source files (e.g. run.c)
  19 - common Makefile fragment and configury (e.g. Make-common.in, aclocal.m4).
  20
  21 In addition "common" contains portions of the system call support
  22 (e.g. callback.c, nltvals.def).
  23
  24 Even though no files are built in this directory, it is still configured
  25 so support for regenerating nltvals.def is present.
  26 \f
  27 Common Makefile Support
  28 =======================
  29
  30 A common configuration framework is available for simulators that want
  31 to use it.  The common framework exists to remove a lot of duplication
  32 in configure.in and Makefile.in, and it also provides a foundation for
  33 enhancing the simulators uniformly (e.g. the more they share in common
  34 the easier a feature added to one is added to all).
  35
  36 The configure.in of a simulator using the common framework should look like:
  37
  38 --- snip ---
  39 dnl Process this file with autoconf to produce a configure script.
  40 sinclude(../common/aclocal.m4)
  41 AC_PREREQ(2.5)dnl
  42 AC_INIT(Makefile.in)
  43
  44 SIM_AC_COMMON
  45
  46 ... target specific additions ...
  47
  48 SIM_AC_OUTPUT
  49 --- snip ---
  50
  51 SIM_AC_COMMON:
  52
  53 - invokes the autoconf macros most often used by the simulators
  54 - defines --enable/--with options usable by all simulators
  55 - initializes sim_link_files/sim_link_links as the set of symbolic links
  56   to set up
  57
  58 SIM_AC_OUTPUT:
  59
  60 - creates the symbolic links defined in sim_link_{files,links}
  61 - creates config.h
  62 - creates the Makefile
  63
  64 The Makefile.in of a simulator using the common framework should look like:
  65
  66 --- snip ---
  67 # Makefile for blah ...
  68 # Copyright blah ...
  69
  70 ## COMMON_PRE_CONFIG_FRAG
  71
  72 # These variables are given default values in COMMON_PRE_CONFIG_FRAG.
  73 # We override the ones we need to here.
  74 # Not all of these need to be mentioned, only the necessary ones.
  75 # In fact it is better to *not* mention ones if the value is the default.
  76
  77 # List of object files, less common parts.
  78 SIM_OBJS =
  79 # List of extra dependencies.
  80 # Generally this consists of simulator specific files included by sim-main.h.
  81 SIM_EXTRA_DEPS =
  82 # List of flags to always pass to $(CC).
  83 SIM_EXTRA_CFLAGS =
  84 # List of extra libraries to link with.
  85 SIM_EXTRA_LIBS =
  86 # List of extra program dependencies.
  87 SIM_EXTRA_LIBDEPS =
  88 # List of main object files for `run'.
  89 SIM_RUN_OBJS = run.o
  90 # Dependency of `all' to build any extra files.
  91 SIM_EXTRA_ALL =
  92 # Dependency of `install' to install any extra files.
  93 SIM_EXTRA_INSTALL =
  94 # Dependency of `clean' to clean any extra files.
  95 SIM_EXTRA_CLEAN =
  96
  97 ## COMMON_POST_CONFIG_FRAG
  98
  99 # Rules need to build $(SIM_OBJS), plus whatever else the target wants.
 100
 101 ... target specific rules ...
 102 --- snip ---
 103
 104 COMMON_{PRE,POST}_CONFIG_FRAG are markers for SIM_AC_OUTPUT to tell it
 105 where to insert the two pieces of common/Make-common.in.
 106 The resulting Makefile is created by doing autoconf substitions on
 107 both the target's Makefile.in and Make-common.in, and inserting
 108 the two pieces of Make-common.in into the target's Makefile.in at
 109 COMMON_{PRE,POST}_CONFIG_FRAG.
 110
 111 Note that SIM_EXTRA_{INSTALL,CLEAN} could be removed and "::" targets
 112 could be used instead.  However, it's not clear yet whether "::" targets
 113 are portable enough.
 114 \f
 115 TAGS support
 116 ============
 117
 118 Many files generate program symbols at compile time.
 119 Such symbols can't be found with grep nor do they normally appear in
 120 the TAGS file.  To get around this, source files can add the comment
 121
 122 /* TAGS: foo1 foo2 */
 123
 124 where foo1, foo2 are program symbols.  Symbols found in such comments
 125 are greppable and appear in the TAGS file.
 126 \f
 127 Generating "configure" files
 128 ============================
 129
 130 For target's using the common framework, "configure" can be generated
 131 by running autoconf.  This works because configure.in contains
 132 "sinclude(../common/aclocal.m4)".
 133
 134 To regenerate the configure files for all targets using the common framework:
 135
 136         $  cd devo/sim
 137         $  make -f Makefile.in autoconf-common
 138
 139 To add a change-log entry to the ChangeLog file for each updated
 140 directory (WARNING - check the modified new-ChangeLog files before
 141 renaming):
 142
 143         $  make -f Makefile.in autoconf-changelog
 144         $  more */new-ChangeLog
 145         $  make -f Makefile.in autoconf-install
 146
 147 In a similar vein, both the configure and config.in files can be
 148 updated using the sequence:
 149
 150         $  cd devo/sim
 151         $  make -f Makefile.in autoheader-common
 152         $  make -f Makefile.in autoheader-changelog
 153         $  more */new-ChangeLog
 154         $  make -f Makefile.in autoheader-install
 155 \f
 156 tconfig.in
 157 ==========
 158
 159 File tconfig.in defines one or more target configuration macros
 160 (e.g. a tm.h file).  There are very few that need defining.
 161 For a list of all of them, see common/tconfig.in.
 162 It contains them all, commented out.
 163 The intent is that a new port can just copy this file and
 164 define the ones it needs.