Fossil SCM

Improvements to the "Fossil Build Process" documentation, with improved comments in related source files. No changes to real code.

drh 2017-11-18 19:58 trunk

Commit 51cf75088cb58094411e3c6871d81153aa1919ecc064e42d0b4a21239b2bd0e4

Parent cee4af9e9c2571e…

5 files changed +11 -4 +1 -1 +2 -2 +1 -1 +41 -16

~ src/makemake.tcl ~ src/mkbuiltin.c ~ src/mkindex.c ~ src/translate.c ~ www/makefile.wiki

M src/makemake.tcl

+11 -4

		--- src/makemake.tcl
		+++ src/makemake.tcl
		@@ -8,10 +8,16 @@
8	8	# win/Makefile.* # makefiles for other windows compilers
9	9	#
10	10	# Run this script while in the "src" subdirectory. Like this:
11	11	#
12	12	# tclsh makemake.tcl
	13	+#
	14	+# Add new source files by listing the files (without their .c suffix)
	15	+# in the "src" variable. Add new resource files to the "extra_files"
	16	+# variable. There are other variables that you can alter, down to
	17	+# the "STOP HERE" comment. The stuff below "STOP HERE" should rarely need
	18	+# to change.
13	19	#
14	20	#############################################################################
15	21
16	22	# Basenames of all source files that get preprocessed using
17	23	# "translate" and "makeheaders". To add new C-language source files to the
		@@ -213,10 +219,15 @@
213	219	lappend SHELL_WIN32_OPTIONS -Daccess=file_access
214	220	lappend SHELL_WIN32_OPTIONS -Dsystem=fossil_system
215	221	lappend SHELL_WIN32_OPTIONS -Dgetenv=fossil_getenv
216	222	lappend SHELL_WIN32_OPTIONS -Dfopen=fossil_fopen
217	223
	224	+# STOP HERE.
	225	+# Unless the build procedures changes, you should not have to edit anything
	226	+# below this line.
	227	+#############################################################################
	228	+
218	229	# Name of the final application
219	230	#
220	231	set name fossil
221	232
222	233	# The "writeln" command sends output to the target makefile.
		@@ -228,14 +239,10 @@
228	239	} else {
229	240	puts $output_file [lindex $args 0]
230	241	}
231	242	}
232	243
233		-# STOP HERE.
234		-# Unless the build procedures changes, you should not have to edit anything
235		-# below this line.
236		-
237	244	# Expand any wildcards in "extra_files"
238	245	set new_extra_files {}
239	246	foreach file $extra_files {
240	247	foreach x [glob -nocomplain $file] {
241	248	lappend new_extra_files $x
242	249

	--- src/makemake.tcl
	+++ src/makemake.tcl
	@@ -8,10 +8,16 @@
8	# win/Makefile.* # makefiles for other windows compilers
9	#
10	# Run this script while in the "src" subdirectory. Like this:
11	#
12	# tclsh makemake.tcl






13	#
14	#############################################################################
15
16	# Basenames of all source files that get preprocessed using
17	# "translate" and "makeheaders". To add new C-language source files to the
	@@ -213,10 +219,15 @@
213	lappend SHELL_WIN32_OPTIONS -Daccess=file_access
214	lappend SHELL_WIN32_OPTIONS -Dsystem=fossil_system
215	lappend SHELL_WIN32_OPTIONS -Dgetenv=fossil_getenv
216	lappend SHELL_WIN32_OPTIONS -Dfopen=fossil_fopen
217





218	# Name of the final application
219	#
220	set name fossil
221
222	# The "writeln" command sends output to the target makefile.
	@@ -228,14 +239,10 @@
228	} else {
229	puts $output_file [lindex $args 0]
230	}
231	}
232
233	# STOP HERE.
234	# Unless the build procedures changes, you should not have to edit anything
235	# below this line.
236
237	# Expand any wildcards in "extra_files"
238	set new_extra_files {}
239	foreach file $extra_files {
240	foreach x [glob -nocomplain $file] {
241	lappend new_extra_files $x
242

	--- src/makemake.tcl
	+++ src/makemake.tcl
	@@ -8,10 +8,16 @@
8	# win/Makefile.* # makefiles for other windows compilers
9	#
10	# Run this script while in the "src" subdirectory. Like this:
11	#
12	# tclsh makemake.tcl
13	#
14	# Add new source files by listing the files (without their .c suffix)
15	# in the "src" variable. Add new resource files to the "extra_files"
16	# variable. There are other variables that you can alter, down to
17	# the "STOP HERE" comment. The stuff below "STOP HERE" should rarely need
18	# to change.
19	#
20	#############################################################################
21
22	# Basenames of all source files that get preprocessed using
23	# "translate" and "makeheaders". To add new C-language source files to the
	@@ -213,10 +219,15 @@
219	lappend SHELL_WIN32_OPTIONS -Daccess=file_access
220	lappend SHELL_WIN32_OPTIONS -Dsystem=fossil_system
221	lappend SHELL_WIN32_OPTIONS -Dgetenv=fossil_getenv
222	lappend SHELL_WIN32_OPTIONS -Dfopen=fossil_fopen
223
224	# STOP HERE.
225	# Unless the build procedures changes, you should not have to edit anything
226	# below this line.
227	#############################################################################
228
229	# Name of the final application
230	#
231	set name fossil
232
233	# The "writeln" command sends output to the target makefile.
	@@ -228,14 +239,10 @@
239	} else {
240	puts $output_file [lindex $args 0]
241	}
242	}
243




244	# Expand any wildcards in "extra_files"
245	set new_extra_files {}
246	foreach file $extra_files {
247	foreach x [glob -nocomplain $file] {
248	lappend new_extra_files $x
249

M src/mkbuiltin.c

+1 -1

		--- src/mkbuiltin.c
		+++ src/mkbuiltin.c
		@@ -2,11 +2,11 @@
2	2	** Copyright (c) 2014 D. Richard Hipp
3	3	**
4	4	** This program is free software; you can redistribute it and/or
5	5	** modify it under the terms of the Simplified BSD License (also
6	6	** known as the "2-Clause License" or "FreeBSD License".)
7		-
	7	+**
8	8	** This program is distributed in the hope that it will be useful,
9	9	** but without any warranty; without even the implied warranty of
10	10	** merchantability or fitness for a particular purpose.
11	11	**
12	12	** Author contact information:
13	13

	--- src/mkbuiltin.c
	+++ src/mkbuiltin.c
	@@ -2,11 +2,11 @@
2	** Copyright (c) 2014 D. Richard Hipp
3	**
4	** This program is free software; you can redistribute it and/or
5	** modify it under the terms of the Simplified BSD License (also
6	** known as the "2-Clause License" or "FreeBSD License".)
7
8	** This program is distributed in the hope that it will be useful,
9	** but without any warranty; without even the implied warranty of
10	** merchantability or fitness for a particular purpose.
11	**
12	** Author contact information:
13

	--- src/mkbuiltin.c
	+++ src/mkbuiltin.c
	@@ -2,11 +2,11 @@
2	** Copyright (c) 2014 D. Richard Hipp
3	**
4	** This program is free software; you can redistribute it and/or
5	** modify it under the terms of the Simplified BSD License (also
6	** known as the "2-Clause License" or "FreeBSD License".)
7	**
8	** This program is distributed in the hope that it will be useful,
9	** but without any warranty; without even the implied warranty of
10	** merchantability or fitness for a particular purpose.
11	**
12	** Author contact information:
13

M src/mkindex.c

+2 -2

		--- src/mkindex.c
		+++ src/mkindex.c
		@@ -2,11 +2,11 @@
2	2	** Copyright (c) 2002 D. Richard Hipp
3	3	**
4	4	** This program is free software; you can redistribute it and/or
5	5	** modify it under the terms of the Simplified BSD License (also
6	6	** known as the "2-Clause License" or "FreeBSD License".)
7		-
	7	+**
8	8	** This program is distributed in the hope that it will be useful,
9	9	** but without any warranty; without even the implied warranty of
10	10	** merchantability or fitness for a particular purpose.
11	11	**
12	12	** Author contact information:
		@@ -31,11 +31,11 @@
31	31	** void function_name(void){
32	32	**
33	33	** Command names can divided into three classes: 1st-tier, 2nd-tier,
34	34	** and test. 1st-tier commands are the most frequently used and the
35	35	** ones that show up with "fossil help". 2nd-tier are seldom-used and/or
36		-** legacy command. Test commands are unsupported commands used for testing
	36	+** legacy commands. Test commands are unsupported commands used for testing
37	37	** and analysis only.
38	38	**
39	39	** Commands are 1st-tier by default. If the command name begins with
40	40	** "test-" or if the command name has a "test" argument, then it becomes
41	41	** a test command. If the command name has a "2nd-tier" argument or ends
42	42

	--- src/mkindex.c
	+++ src/mkindex.c
	@@ -2,11 +2,11 @@
2	** Copyright (c) 2002 D. Richard Hipp
3	**
4	** This program is free software; you can redistribute it and/or
5	** modify it under the terms of the Simplified BSD License (also
6	** known as the "2-Clause License" or "FreeBSD License".)
7
8	** This program is distributed in the hope that it will be useful,
9	** but without any warranty; without even the implied warranty of
10	** merchantability or fitness for a particular purpose.
11	**
12	** Author contact information:
	@@ -31,11 +31,11 @@
31	** void function_name(void){
32	**
33	** Command names can divided into three classes: 1st-tier, 2nd-tier,
34	** and test. 1st-tier commands are the most frequently used and the
35	** ones that show up with "fossil help". 2nd-tier are seldom-used and/or
36	** legacy command. Test commands are unsupported commands used for testing
37	** and analysis only.
38	**
39	** Commands are 1st-tier by default. If the command name begins with
40	** "test-" or if the command name has a "test" argument, then it becomes
41	** a test command. If the command name has a "2nd-tier" argument or ends
42

	--- src/mkindex.c
	+++ src/mkindex.c
	@@ -2,11 +2,11 @@
2	** Copyright (c) 2002 D. Richard Hipp
3	**
4	** This program is free software; you can redistribute it and/or
5	** modify it under the terms of the Simplified BSD License (also
6	** known as the "2-Clause License" or "FreeBSD License".)
7	**
8	** This program is distributed in the hope that it will be useful,
9	** but without any warranty; without even the implied warranty of
10	** merchantability or fitness for a particular purpose.
11	**
12	** Author contact information:
	@@ -31,11 +31,11 @@
31	** void function_name(void){
32	**
33	** Command names can divided into three classes: 1st-tier, 2nd-tier,
34	** and test. 1st-tier commands are the most frequently used and the
35	** ones that show up with "fossil help". 2nd-tier are seldom-used and/or
36	** legacy commands. Test commands are unsupported commands used for testing
37	** and analysis only.
38	**
39	** Commands are 1st-tier by default. If the command name begins with
40	** "test-" or if the command name has a "test" argument, then it becomes
41	** a test command. If the command name has a "2nd-tier" argument or ends
42

M src/translate.c

+1 -1

		--- src/translate.c
		+++ src/translate.c
		@@ -2,11 +2,11 @@
2	2	** Copyright (c) 2002 D. Richard Hipp
3	3	**
4	4	** This program is free software; you can redistribute it and/or
5	5	** modify it under the terms of the Simplified BSD License (also
6	6	** known as the "2-Clause License" or "FreeBSD License".)
7		-
	7	+**
8	8	** This program is distributed in the hope that it will be useful,
9	9	** but without any warranty; without even the implied warranty of
10	10	** merchantability or fitness for a particular purpose.
11	11	**
12	12	** Author contact information:
13	13

	--- src/translate.c
	+++ src/translate.c
	@@ -2,11 +2,11 @@
2	** Copyright (c) 2002 D. Richard Hipp
3	**
4	** This program is free software; you can redistribute it and/or
5	** modify it under the terms of the Simplified BSD License (also
6	** known as the "2-Clause License" or "FreeBSD License".)
7
8	** This program is distributed in the hope that it will be useful,
9	** but without any warranty; without even the implied warranty of
10	** merchantability or fitness for a particular purpose.
11	**
12	** Author contact information:
13

	--- src/translate.c
	+++ src/translate.c
	@@ -2,11 +2,11 @@
2	** Copyright (c) 2002 D. Richard Hipp
3	**
4	** This program is free software; you can redistribute it and/or
5	** modify it under the terms of the Simplified BSD License (also
6	** known as the "2-Clause License" or "FreeBSD License".)
7	**
8	** This program is distributed in the hope that it will be useful,
9	** but without any warranty; without even the implied warranty of
10	** merchantability or fitness for a particular purpose.
11	**
12	** Author contact information:
13

M www/makefile.wiki

+41 -16

		--- www/makefile.wiki
		+++ www/makefile.wiki
		@@ -24,32 +24,31 @@
24	24
25	25	Each preprocessor program is a separate C program implemented in
26	26	a single file of C source code. The three preprocessor programs
27	27	are:
28	28
29		- 1. mkindex.c
30		- 2. translate.c
31		- 3. makeheaders.c
	29	+ 1. [/file/src/mkindex.c \| mkindex.c]
	30	+ 2. [/file/src/translate.c \| translate.c]
	31	+ 3. [/file/src/makeheaders.c \| makeheaders.c]
32	32
33		-Fossil makes use of [http://www.sqlite.org/ \| SQLite] for on-disk
	33	+Fossil uses [http://www.sqlite.org/ \| SQLite] for on-disk
34	34	storage. The SQLite implementation is contained in three source
35	35	code files that do not participate in the preprocessing steps.
36	36	These three files that implement SQLite are:
37	37
38	38	4. sqlite3.c
39	39	5. sqlite3.h
40	40	6. shell.c
41	41
42		-The sqlite3.c and sqlite3.h source files are byte-for-byte copies of a
	42	+All three SQLite source files are byte-for-byte copies of files by
	43	+the same name in the
43	44	standard [http://www.sqlite.org/amalgamation.html \| amalgamation].
44		-The shell.c source file is code for the SQLite
45		-[http://www.sqlite.org/sqlite.html \| command-line shell] that is used
46		-to help implement the [/help/sqlite3 \| fossil sql] command. The
47		-shell.c source file is also a byte-for-byte copy of the
48		-shell.c file from the SQLite release.
	45	+The sqlite3.c file implements the database engine. The shell.c file
	46	+implements the command-line shell, which is accessed in fossil using
	47	+the [/help?cmd=sqlite3 \| fossil sql] command.
49	48
50		-The SQLite shell.c file uses the [https://github.com/antirez/linenoise \|
	49	+The shell.c command-line shell uses the [https://github.com/antirez/linenoise \|
51	50	linenoise] library to implement line editing. linenoise comprises two
52	51	source files which were copied from the upstream repository with only
53	52	very minor portability edits:
54	53
55	54	7. linenoise.c
		@@ -58,24 +57,31 @@
58	57	The TH1 script engine is implemented using files:
59	58
60	59	9. th.c
61	60	10. th.h
62	61
63		-These two files are imports like the SQLite source files,
64		-and so are not preprocessed.
	62	+The proprocessing steps are omitted for all of these imported
	63	+files.
65	64
66	65	The VERSION.h header file is generated from other information sources
67	66	using a small program called:
68	67
69		- 11. mkversion.c
	68	+ 11. [/file/src/mkversion.c \| mkversion.c]
70	69
71	70	The builtin_data.h header file contains the definitions of C-language
72	71	byte-array constants that contain various resources such as scripts and
73	72	images. The builtin_data.h header file is generate from the original
74	73	resource files using a small program called:
75	74
76		- 12 mkbuiltin.c
	75	+ 12 [/file/src/mkbuiltin.c \| mkbuildin.c]
	76	+
	77	+Examples of built-in resources include the [/file/src/diff.tcl \| diff.tcl]
	78	+script used to implement the --tk option to [/help?cmd=diff\| fossil diff],
	79	+the [/file/src/markdown.md \| markdown documentation], and the various
	80	+CSS scripts, headers, and footers used to implement built-in skins. New
	81	+resources files are added to the "extra_files" variable in
	82	+[/file/src/makemake.tcl \| makemake.tcl].
77	83
78	84	The src/ subdirectory also contains documentation about the
79	85	makeheaders preprocessor program:
80	86
81	87	13. [../src/makeheaders.html \| makeheaders.html]
		@@ -87,14 +93,33 @@
87	93
88	94	Running this Tcl script will automatically regenerate all makefiles.
89	95	In order to add a new source file to the Fossil implementation, simply
90	96	edit makemake.tcl to add the new filename, then rerun the script, and
91	97	all of the makefiles for all targets will be rebuild.
	98	+
	99	+There is an option code verification step implemented using
	100	+
	101	+ 15. [/file/src/codecheck1.c \| codecheck1.c]
	102	+
	103	+This file implements a small utility program ("codecheck1")
	104	+that scans other Fossil source files looking for errors in printf-style
	105	+format strings.
	106	+The codecheck1 utility detects missing or surplus arguments on
	107	+printf-like functions and dangerous uses of "%s" that might
	108	+permit SQL injection or cross-site scripting attacks. This code
	109	+check step is run automatically on each build of Fossil, and can
	110	+also be run separately by typing "make codecheck". Note that the
	111	+built-in printf format checking of GCC does not function for Fossil
	112	+since Fossil implements its own printf (in the
	113	+[/file/src/printf.c \| printf.c] source file) that includes special
	114	+features and formatting letters that are useful to Fossil. The
	115	+codecheck1 utility can be seen as an enhanced application-specific
	116	+replacement for the GCC printf format checker.
92	117
93	118	Finally, there is one of the makefiles generated by makemake.tcl:
94	119
95		- 15. main.mk
	120	+ 16. main.mk
96	121
97	122	The main.mk makefile is invoked from the Makefile in the top-level
98	123	directory. The main.mk is generated by makemake.tcl and should not
99	124	be hand edited. Other makefiles generated by makemake.tcl are in
100	125	other subdirectories (currently all in the win/ subdirectory).
101	126

	--- www/makefile.wiki
	+++ www/makefile.wiki
	@@ -24,32 +24,31 @@
24
25	Each preprocessor program is a separate C program implemented in
26	a single file of C source code. The three preprocessor programs
27	are:
28
29	1. mkindex.c
30	2. translate.c
31	3. makeheaders.c
32
33	Fossil makes use of [http://www.sqlite.org/ \| SQLite] for on-disk
34	storage. The SQLite implementation is contained in three source
35	code files that do not participate in the preprocessing steps.
36	These three files that implement SQLite are:
37
38	4. sqlite3.c
39	5. sqlite3.h
40	6. shell.c
41
42	The sqlite3.c and sqlite3.h source files are byte-for-byte copies of a

43	standard [http://www.sqlite.org/amalgamation.html \| amalgamation].
44	The shell.c source file is code for the SQLite
45	[http://www.sqlite.org/sqlite.html \| command-line shell] that is used
46	to help implement the [/help/sqlite3 \| fossil sql] command. The
47	shell.c source file is also a byte-for-byte copy of the
48	shell.c file from the SQLite release.
49
50	The SQLite shell.c file uses the [https://github.com/antirez/linenoise \|
51	linenoise] library to implement line editing. linenoise comprises two
52	source files which were copied from the upstream repository with only
53	very minor portability edits:
54
55	7. linenoise.c
	@@ -58,24 +57,31 @@
58	The TH1 script engine is implemented using files:
59
60	9. th.c
61	10. th.h
62
63	These two files are imports like the SQLite source files,
64	and so are not preprocessed.
65
66	The VERSION.h header file is generated from other information sources
67	using a small program called:
68
69	11. mkversion.c
70
71	The builtin_data.h header file contains the definitions of C-language
72	byte-array constants that contain various resources such as scripts and
73	images. The builtin_data.h header file is generate from the original
74	resource files using a small program called:
75
76	12 mkbuiltin.c







77
78	The src/ subdirectory also contains documentation about the
79	makeheaders preprocessor program:
80
81	13. [../src/makeheaders.html \| makeheaders.html]
	@@ -87,14 +93,33 @@
87
88	Running this Tcl script will automatically regenerate all makefiles.
89	In order to add a new source file to the Fossil implementation, simply
90	edit makemake.tcl to add the new filename, then rerun the script, and
91	all of the makefiles for all targets will be rebuild.



















92
93	Finally, there is one of the makefiles generated by makemake.tcl:
94
95	15. main.mk
96
97	The main.mk makefile is invoked from the Makefile in the top-level
98	directory. The main.mk is generated by makemake.tcl and should not
99	be hand edited. Other makefiles generated by makemake.tcl are in
100	other subdirectories (currently all in the win/ subdirectory).
101

	--- www/makefile.wiki
	+++ www/makefile.wiki
	@@ -24,32 +24,31 @@
24
25	Each preprocessor program is a separate C program implemented in
26	a single file of C source code. The three preprocessor programs
27	are:
28
29	1. [/file/src/mkindex.c \| mkindex.c]
30	2. [/file/src/translate.c \| translate.c]
31	3. [/file/src/makeheaders.c \| makeheaders.c]
32
33	Fossil uses [http://www.sqlite.org/ \| SQLite] for on-disk
34	storage. The SQLite implementation is contained in three source
35	code files that do not participate in the preprocessing steps.
36	These three files that implement SQLite are:
37
38	4. sqlite3.c
39	5. sqlite3.h
40	6. shell.c
41
42	All three SQLite source files are byte-for-byte copies of files by
43	the same name in the
44	standard [http://www.sqlite.org/amalgamation.html \| amalgamation].
45	The sqlite3.c file implements the database engine. The shell.c file
46	implements the command-line shell, which is accessed in fossil using
47	the [/help?cmd=sqlite3 \| fossil sql] command.


48
49	The shell.c command-line shell uses the [https://github.com/antirez/linenoise \|
50	linenoise] library to implement line editing. linenoise comprises two
51	source files which were copied from the upstream repository with only
52	very minor portability edits:
53
54	7. linenoise.c
	@@ -58,24 +57,31 @@
57	The TH1 script engine is implemented using files:
58
59	9. th.c
60	10. th.h
61
62	The proprocessing steps are omitted for all of these imported
63	files.
64
65	The VERSION.h header file is generated from other information sources
66	using a small program called:
67
68	11. [/file/src/mkversion.c \| mkversion.c]
69
70	The builtin_data.h header file contains the definitions of C-language
71	byte-array constants that contain various resources such as scripts and
72	images. The builtin_data.h header file is generate from the original
73	resource files using a small program called:
74
75	12 [/file/src/mkbuiltin.c \| mkbuildin.c]
76
77	Examples of built-in resources include the [/file/src/diff.tcl \| diff.tcl]
78	script used to implement the --tk option to [/help?cmd=diff\| fossil diff],
79	the [/file/src/markdown.md \| markdown documentation], and the various
80	CSS scripts, headers, and footers used to implement built-in skins. New
81	resources files are added to the "extra_files" variable in
82	[/file/src/makemake.tcl \| makemake.tcl].
83
84	The src/ subdirectory also contains documentation about the
85	makeheaders preprocessor program:
86
87	13. [../src/makeheaders.html \| makeheaders.html]
	@@ -87,14 +93,33 @@
93
94	Running this Tcl script will automatically regenerate all makefiles.
95	In order to add a new source file to the Fossil implementation, simply
96	edit makemake.tcl to add the new filename, then rerun the script, and
97	all of the makefiles for all targets will be rebuild.
98
99	There is an option code verification step implemented using
100
101	15. [/file/src/codecheck1.c \| codecheck1.c]
102
103	This file implements a small utility program ("codecheck1")
104	that scans other Fossil source files looking for errors in printf-style
105	format strings.
106	The codecheck1 utility detects missing or surplus arguments on
107	printf-like functions and dangerous uses of "%s" that might
108	permit SQL injection or cross-site scripting attacks. This code
109	check step is run automatically on each build of Fossil, and can
110	also be run separately by typing "make codecheck". Note that the
111	built-in printf format checking of GCC does not function for Fossil
112	since Fossil implements its own printf (in the
113	[/file/src/printf.c \| printf.c] source file) that includes special
114	features and formatting letters that are useful to Fossil. The
115	codecheck1 utility can be seen as an enhanced application-specific
116	replacement for the GCC printf format checker.
117
118	Finally, there is one of the makefiles generated by makemake.tcl:
119
120	16. main.mk
121
122	The main.mk makefile is invoked from the Makefile in the top-level
123	directory. The main.mk is generated by makemake.tcl and should not
124	be hand edited. Other makefiles generated by makemake.tcl are in
125	other subdirectories (currently all in the win/ subdirectory).
126

Fossil SCM

Keyboard Shortcuts