Fossil

Check-in [51cf7508]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Improvements to the "Fossil Build Process" documentation, with improved comments in related source files. No changes to real code.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 51cf75088cb58094411e3c6871d81153aa1919ecc064e42d0b4a21239b2bd0e4
User & Date: drh 2017-11-18 19:58:54
Context
2017-11-22
19:01
Improvements to the coding-style guidelines from Johan Kuuse. check-in: 49cde9fc user: drh tags: trunk
2017-11-18
19:58
Improvements to the "Fossil Build Process" documentation, with improved comments in related source files. No changes to real code. check-in: 51cf7508 user: drh tags: trunk
17:49
Fix a crash that can occur in search when the FTS4 snippet() function returns NULL. check-in: cee4af9e user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/makemake.tcl.

6
7
8
9
10
11
12






13
14
15
16
17
18
19
...
211
212
213
214
215
216
217





218
219
220
221
222
223
224
...
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
#     src/main.mk           # makefile for all unix systems
#     win/Makefile.mingw    # makefile for mingw on windows
#     win/Makefile.*        # makefiles for other windows compilers
#
# Run this script while in the "src" subdirectory.  Like this:
#
#      tclsh makemake.tcl






#
#############################################################################

# Basenames of all source files that get preprocessed using
# "translate" and "makeheaders".  To add new C-language source files to the
# project, simply add the basename to this list and rerun this script.
#
................................................................................
#
set SHELL_WIN32_OPTIONS $SHELL_OPTIONS
lappend SHELL_WIN32_OPTIONS -Daccess=file_access
lappend SHELL_WIN32_OPTIONS -Dsystem=fossil_system
lappend SHELL_WIN32_OPTIONS -Dgetenv=fossil_getenv
lappend SHELL_WIN32_OPTIONS -Dfopen=fossil_fopen






# Name of the final application
#
set name fossil

# The "writeln" command sends output to the target makefile.
#
proc writeln {args} {
................................................................................
  if {[lindex $args 0]=="-nonewline"} {
    puts -nonewline $output_file [lindex $args 1]
  } else {
    puts $output_file [lindex $args 0]
  }
}

# STOP HERE.
# Unless the build procedures changes, you should not have to edit anything
# below this line.

# Expand any wildcards in "extra_files"
set new_extra_files {}
foreach file $extra_files {
  foreach x [glob -nocomplain $file] {
    lappend new_extra_files $x
  }
}







>
>
>
>
>
>







 







>
>
>
>
>







 







<
<
<
<







6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
...
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
...
237
238
239
240
241
242
243




244
245
246
247
248
249
250
#     src/main.mk           # makefile for all unix systems
#     win/Makefile.mingw    # makefile for mingw on windows
#     win/Makefile.*        # makefiles for other windows compilers
#
# Run this script while in the "src" subdirectory.  Like this:
#
#      tclsh makemake.tcl
#
# Add new source files by listing the files (without their .c suffix)
# in the "src" variable.  Add new resource files to the "extra_files"
# variable.  There are other variables that you can alter, down to
# the "STOP HERE" comment.  The stuff below "STOP HERE" should rarely need
# to change.
#
#############################################################################

# Basenames of all source files that get preprocessed using
# "translate" and "makeheaders".  To add new C-language source files to the
# project, simply add the basename to this list and rerun this script.
#
................................................................................
#
set SHELL_WIN32_OPTIONS $SHELL_OPTIONS
lappend SHELL_WIN32_OPTIONS -Daccess=file_access
lappend SHELL_WIN32_OPTIONS -Dsystem=fossil_system
lappend SHELL_WIN32_OPTIONS -Dgetenv=fossil_getenv
lappend SHELL_WIN32_OPTIONS -Dfopen=fossil_fopen

# STOP HERE.
# Unless the build procedures changes, you should not have to edit anything
# below this line.
#############################################################################

# Name of the final application
#
set name fossil

# The "writeln" command sends output to the target makefile.
#
proc writeln {args} {
................................................................................
  if {[lindex $args 0]=="-nonewline"} {
    puts -nonewline $output_file [lindex $args 1]
  } else {
    puts $output_file [lindex $args 0]
  }
}





# Expand any wildcards in "extra_files"
set new_extra_files {}
foreach file $extra_files {
  foreach x [glob -nocomplain $file] {
    lappend new_extra_files $x
  }
}

Changes to src/mkbuiltin.c.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/*
** Copyright (c) 2014 D. Richard Hipp
**
** This program is free software; you can redistribute it and/or
** modify it under the terms of the Simplified BSD License (also
** known as the "2-Clause License" or "FreeBSD License".)

** This program is distributed in the hope that it will be useful,
** but without any warranty; without even the implied warranty of
** merchantability or fitness for a particular purpose.
**
** Author contact information:
**   drh@hwaci.com
**   http://www.hwaci.com/drh/






|







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

Changes to src/mkindex.c.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
..
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
/*
** Copyright (c) 2002 D. Richard Hipp
**
** This program is free software; you can redistribute it and/or
** modify it under the terms of the Simplified BSD License (also
** known as the "2-Clause License" or "FreeBSD License".)

** This program is distributed in the hope that it will be useful,
** but without any warranty; without even the implied warranty of
** merchantability or fitness for a particular purpose.
**
** Author contact information:
**   drh@hwaci.com
**   http://www.hwaci.com/drh/
................................................................................
** implements the webpage or command.  The form of this function is:
**
**       void function_name(void){
**
** Command names can divided into three classes:  1st-tier, 2nd-tier,
** and test.  1st-tier commands are the most frequently used and the
** ones that show up with "fossil help".  2nd-tier are seldom-used and/or
** legacy command.  Test commands are unsupported commands used for testing
** and analysis only.
**
** Commands are 1st-tier by default.  If the command name begins with
** "test-" or if the command name has a "test" argument, then it becomes
** a test command.  If the command name has a "2nd-tier" argument or ends
** with a "*" character, it is second tier.  Examples:
**






|







 







|







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

Changes to src/translate.c.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/*
** Copyright (c) 2002 D. Richard Hipp
**
** This program is free software; you can redistribute it and/or
** modify it under the terms of the Simplified BSD License (also
** known as the "2-Clause License" or "FreeBSD License".)

** This program is distributed in the hope that it will be useful,
** but without any warranty; without even the implied warranty of
** merchantability or fitness for a particular purpose.
**
** Author contact information:
**   drh@hwaci.com
**   http://www.hwaci.com/drh/






|







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

Changes to www/makefile.wiki.

22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

43
44
45

46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76







77
78
79
80
81
82
83
..
85
86
87
88
89
90
91



















92
93
94
95
96
97
98
99
100
101
102
source tree.  The src/ subdirectory contains all code, including
the code for the separate preprocessor programs.

Each preprocessor program is a separate C program implemented in
a single file of C source code.  The three preprocessor programs
are:

  1.  mkindex.c
  2.  translate.c
  3.  makeheaders.c

Fossil makes use of [http://www.sqlite.org/ | SQLite] for on-disk
storage.  The SQLite implementation is contained in three source
code files that do not participate in the preprocessing steps.
These three files that implement SQLite are:

  4.  sqlite3.c
  5.  sqlite3.h
  6.  shell.c

The sqlite3.c and sqlite3.h source files are byte-for-byte copies of a

standard [http://www.sqlite.org/amalgamation.html | amalgamation].
The shell.c source file is code for the SQLite
[http://www.sqlite.org/sqlite.html | command-line shell] that is used

to help implement the [/help/sqlite3 | fossil sql] command.  The
shell.c source file is also a byte-for-byte copy of the
shell.c file from the SQLite release.

The SQLite shell.c file uses the [https://github.com/antirez/linenoise |
linenoise] library to implement line editing.  linenoise comprises two
source files which were copied from the upstream repository with only
very minor portability edits:

  7.  linenoise.c
  8.  linenoise.h

The TH1 script engine is implemented using files:

  9.  th.c
  10.  th.h

These two files are imports like the SQLite source files,
and so are not preprocessed.

The VERSION.h header file is generated from other information sources
using a small program called:

  11.  mkversion.c

The builtin_data.h header file contains the definitions of C-language
byte-array constants that contain various resources such as scripts and
images.  The builtin_data.h header file is generate from the original
resource files using a small program called:

  12   mkbuiltin.c








The src/ subdirectory also contains documentation about the
makeheaders preprocessor program:

  13.  [../src/makeheaders.html | makeheaders.html]

Click on the link to read this documentation.  In addition there is
................................................................................

  14.  makemake.tcl

Running this Tcl script will automatically regenerate all makefiles.
In order to add a new source file to the Fossil implementation, simply
edit makemake.tcl to add the new filename, then rerun the script, and
all of the makefiles for all targets will be rebuild.




















Finally, there is one of the makefiles generated by makemake.tcl:

  15.  main.mk

The main.mk makefile is invoked from the Makefile in the top-level
directory.  The main.mk is generated by makemake.tcl and should not
be hand edited.  Other makefiles generated by makemake.tcl are in
other subdirectories (currently all in the win/ subdirectory).

All the other files in the src/ subdirectory (79 files at the time of







|
|
|

|








|
>

<
|
>
|
<
<

|












|
|




|






|
>
>
>
>
>
>
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>



|







22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

45
46
47


48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
..
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
source tree.  The src/ subdirectory contains all code, including
the code for the separate preprocessor programs.

Each preprocessor program is a separate C program implemented in
a single file of C source code.  The three preprocessor programs
are:

  1.  [/file/src/mkindex.c | mkindex.c]
  2.  [/file/src/translate.c | translate.c]
  3.  [/file/src/makeheaders.c | makeheaders.c]

Fossil uses [http://www.sqlite.org/ | SQLite] for on-disk
storage.  The SQLite implementation is contained in three source
code files that do not participate in the preprocessing steps.
These three files that implement SQLite are:

  4.  sqlite3.c
  5.  sqlite3.h
  6.  shell.c

All three SQLite source files are byte-for-byte copies of files by
the same name in the
standard [http://www.sqlite.org/amalgamation.html | amalgamation].

The sqlite3.c file implements the database engine.  The shell.c file
implements the command-line shell, which is accessed in fossil using
the [/help?cmd=sqlite3 | fossil sql] command.



The shell.c command-line shell uses the [https://github.com/antirez/linenoise |
linenoise] library to implement line editing.  linenoise comprises two
source files which were copied from the upstream repository with only
very minor portability edits:

  7.  linenoise.c
  8.  linenoise.h

The TH1 script engine is implemented using files:

  9.  th.c
  10.  th.h

The proprocessing steps are omitted for all of these imported
files.

The VERSION.h header file is generated from other information sources
using a small program called:

  11.  [/file/src/mkversion.c | mkversion.c]

The builtin_data.h header file contains the definitions of C-language
byte-array constants that contain various resources such as scripts and
images.  The builtin_data.h header file is generate from the original
resource files using a small program called:

  12   [/file/src/mkbuiltin.c | mkbuildin.c]

Examples of built-in resources include the [/file/src/diff.tcl | diff.tcl]
script used to implement the --tk option to [/help?cmd=diff| fossil diff],
the [/file/src/markdown.md | markdown documentation], and the various
CSS scripts, headers, and footers used to implement built-in skins.  New
resources files are added to the "extra_files" variable in
[/file/src/makemake.tcl | makemake.tcl].

The src/ subdirectory also contains documentation about the
makeheaders preprocessor program:

  13.  [../src/makeheaders.html | makeheaders.html]

Click on the link to read this documentation.  In addition there is
................................................................................

  14.  makemake.tcl

Running this Tcl script will automatically regenerate all makefiles.
In order to add a new source file to the Fossil implementation, simply
edit makemake.tcl to add the new filename, then rerun the script, and
all of the makefiles for all targets will be rebuild.

There is an option code verification step implemented using

  15.  [/file/src/codecheck1.c | codecheck1.c]

This file implements a small utility program ("codecheck1")
that scans other Fossil source files looking for errors in printf-style 
format strings.
The codecheck1 utility detects missing or surplus arguments on 
printf-like functions and dangerous uses of "%s" that might
permit SQL injection or cross-site scripting attacks.  This code
check step is run automatically on each build of Fossil, and can
also be run separately by typing "make codecheck".  Note that the
built-in printf format checking of GCC does not function for Fossil
since Fossil implements its own printf (in the
[/file/src/printf.c | printf.c] source file) that includes special
features and formatting letters that are useful to Fossil.  The
codecheck1 utility can be seen as an enhanced application-specific
replacement for the GCC printf format checker.

Finally, there is one of the makefiles generated by makemake.tcl:

  16.  main.mk

The main.mk makefile is invoked from the Makefile in the top-level
directory.  The main.mk is generated by makemake.tcl and should not
be hand edited.  Other makefiles generated by makemake.tcl are in
other subdirectories (currently all in the win/ subdirectory).

All the other files in the src/ subdirectory (79 files at the time of