AnaGram interim repo (temporary): doc/devel/make.txt annotate

annotate doc/devel/make.txt @ 24:a4899cdfc2d6 default tip

Obfuscate the regexps to strip off the IBM compiler's copyright banners. I don't want bots scanning github to think they're real copyright notices because that could cause real problems.

author	David A. Holland
date	Mon, 13 Jun 2022 00:40:23 -0400
parents	bb115deb6fb2
children

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.

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

annotate doc/devel/make.txt @ 24:a4899cdfc2d6 default tip