Commit | Line | Data |
---|---|---|
b69cc8ab AC |
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 | |
b04500b2 | 123 | $ make -f Makefile.in autoconf-install |
b69cc8ab | 124 | |
96527c4e AC |
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 | |
b69cc8ab | 133 |