Mercurial > ~dholland > hg > ag > index.cgi

annotate doc/devel/make.txt @ 21:1c9dac05d040

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add lint-style FALLTHROUGH annotations to fallthrough cases. (in the parse engine and thus the output code) Document this, because the old output causes warnings with gcc10.
author David A. Holland
date Mon, 13 Jun 2022 00:04:38 -0400
parents bb115deb6fb2
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
1 Things you should do when developing:
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
2
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
3 - Configure with --enable-maintainer-mode. (See install.txt.)
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
4
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
5 - Set up both a native and a Windows build tree.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
6
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
7 - Create a directory "bin" under the top level of the source tree,
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
8 and copy a known working version of agcl there. (See below.)
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
9
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
10 Useful make targets and options:
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
11
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
12 all Compile everything.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
13 rules Update the make rules.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
14 agfiles Generate AG output from syntax files.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
15 agclean Remove AG output files.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
16 clean Remove object files and executables.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
17 distclean Remove all compiler-generated material.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
18 install Install everything.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
19
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
20 SAFE=1 Compile with "safe" AnaGram (see below)
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
21 UNSAFE=1 Compile with "unsafe" AnaGram (see below)
20
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
22 AGFORCE=1 Force the agfiles target to rebuild.
0
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
23
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
24 If you add a file to the build, rerun "make rules" in the affected
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
25 build directories. If you add a whole directory, you need to rerun the
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
26 configure script to generate the new makefile. You can do this in an
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
27 existing build directory by running "./config.status", which remembers
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
28 the options you gave to configure.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
29
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
30 Dependency tracking for header files is automatic.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
31
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
32 If you want to remove a header file from the build, the easiest way is
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
33 to make sure it isn't used (e.g., by putting an #error in it and
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
34 building) before actually deleting it. Otherwise you may need to blow
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
35 away the depend files (depend.mk and *.u or *.d) to keep make from
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
36 complaining that it doesn't exist.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
37
20
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
38 Note that the 'agfiles' target will only rebuild the AnaGram output if
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
39 it appears to be out of date, unless you specify AGFORCE=1. If you
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
40 aren't certain whether it really rebuilt, check the date stamp in the
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
41 output header file.
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
42
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
43
0
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
44 Bootstrapping notes:
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
45
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
46 AnaGram is partly written using itself. This creates the potential for
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
47 various kinds of problems.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
48
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
49 The distribution archives ship with up-to-date versions of the
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
50 generated code; if you aren't developing, you should be able to just
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
51 use those and everything should be ok.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
52
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
53 If you *are* developing, the following precautions are taken:
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
54
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
55 - By default, the build runs $(TOP)/bin/agcl, which you should
20
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
56 update by hand as you see fit. Note: update it from the copy
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
57 the build produces in anagram/run, not the one in anagram/agcl.
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
58 The latter doesn't have the checksums in it and won't run.
0
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
59
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
60 - If you set SAFE (e.g., make SAFE=1) the build system will run
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
61 $(TOP)/bin/safe-agcl instead, the idea being that you can be
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
62 be very conservative about updating this and use it as a
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
63 fallback if you manage to delete or break $(TOP)/bin/agcl.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
64
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
65 - If you set UNSAFE (e.g., make UNSAFE=1) the build system will
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
66 run the most recent native agcl right out of the build tree.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
67 Use with due caution.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
68
17
12171da8943f Don't refer to CVS.
David A. Holland
parents: 0
diff changeset
69 - The AG-generated code used in the build is kept in source
12171da8943f Don't refer to CVS.
David A. Holland
parents: 0
diff changeset
70 control, so if all else fails you can revert to a clean version
12171da8943f Don't refer to CVS.
David A. Holland
parents: 0
diff changeset
71 that way. Be sure to revert matching .cpp and .h files, or the
12171da8943f Don't refer to CVS.
David A. Holland
parents: 0
diff changeset
72 build will fail.
0
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
73
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
74 Note that $(TOP)/bin is neither created nor populated by default;
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
75 if developing you should set it up yourself with a suitable agcl
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
76 executable.
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
77
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
78 Also note that if you are developing you should always configure with
20
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
79 --enable-maintainer-mode, and this *requires* $(TOP)/bin/agcl to
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
80 exist. This also creates a minor bootstrap problem: if you don't
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
81 already have an agcl to place in $(TOP)/bin, you have to compile
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
82 one. The easiest way is as follows:
0
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
83
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
84 path-to-source/configure native
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
85 make rules
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
86 make
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
87 mkdir path-to-source/bin
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
88 cp anagram/run/agcl path-to-source/bin/agcl
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
89 ./config.status --enable-maintainer-mode
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
90 make rules
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
91 make
13d2b8934445 Import AnaGram (near-)release tree into Mercurial.
David A. Holland
parents:
diff changeset
92
20
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
93 And finally, note that the 'agfiles' target depends make-style, that
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
94 is, by timestamp, on the agcl executable selected. If reverting to an
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
95 older version, including via SAFE=1, it is a good idea to also
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
96 AGFORCE=1 on the make command line, or run the 'agclean' target
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
97 first. (There is also no such dependency when maintainer mode is not
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
98 enabled, because that would preclude building from scratch.)
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
99
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
100 The premise is that changes to the sources are much more common than
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
101 material changes to the output that require rebuilding the parsers
bb115deb6fb2 Improve agfiles rule.
David A. Holland
parents: 17
diff changeset
102 used in AnaGram itself.