-
Notifications
You must be signed in to change notification settings - Fork 0
/
HACKING
198 lines (148 loc) · 7.6 KB
/
HACKING
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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
90
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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
# -*-text-*-
The 'ads-github-tools' project is built using the GNU Autotools (Automake,
Autoconf, etc.)
This file contains the following sections:
* Building from a Source Tarball
* Building from Git
Building from a Source Tarball
==============================
If you simply want to build the 'ads-github-tools' project (as opposed to
hacking on the codebase), the easiest thing to do is obtain a source
distribution tarball of the version of the project you wish to build.
Source tarballs are available from the project's website:
http://salewski.email/ads-github-tools/
specifically on the Downloads Archive page:
http://salewski.email/ads-github-tools/downloads/
[Writing in 2022-10, the source tarballs are also available in the project's
Git repository on the 'gh-pages' branch, in the 'downloads/' directory. We
currently follow this practice because the number of release tarballs is
small, and doing so makes hosting the project's website via GitHub Pages
easy. However, that practice may not continue indefinitely, since it
artificially bloats the size of the Git repo. Since ads-github-tools-0.3.2,
some of the project's dependencies have been "vendored" (included with the
project in-tree under the 'src/third-party/' directory), which makes each
distribution tarball a little over 7M (as opposed to about 250K without those
vendored sources).]
Using a source tarball relieves you of having access to specific versions of
the GNU Autotools, etc.
Note that the curl(1) command line in the following example is using POSIX
shell expansion to request not only the source tarball, but also the various
checksums files that are made available for it. (Curl needs one '-O' option
for each such expansion in order to save the content of the files locally,
hence the '-OOOOOOOOO' option.)
$ cd /usr/local/src
.../src$ curl -OOOOOOOOO -R http://salewski.email/ads-github-tools/downloads/ads-github-tools-0.3.4.tar.gz{,.SHA-{1,256,384,512},.SHA3-{224,256,384,512}}
.../src$ ls | grep ads-github
ads-github-tools-0.3.4.tar.gz
ads-github-tools-0.3.4.tar.gz.SHA-1
ads-github-tools-0.3.4.tar.gz.SHA-256
ads-github-tools-0.3.4.tar.gz.SHA-384
ads-github-tools-0.3.4.tar.gz.SHA-512
ads-github-tools-0.3.4.tar.gz.SHA3-224
ads-github-tools-0.3.4.tar.gz.SHA3-256
ads-github-tools-0.3.4.tar.gz.SHA3-384
ads-github-tools-0.3.4.tar.gz.SHA3-512
.../src$
.../src$ $ sha512sum --check ads-github-tools-0.3.4.tar.gz.SHA-512
./ads-github-tools-0.3.4.tar.gz: OK
.../src$
.../src$ gzip -dc ads-github-tools-0.3.4.gz | tar xf -
.../src$ cd ads-github-tools-0.3.4
.../src/ads-github-tools-0.3.4$ ./configure --prefix=/path/to/whatever
.../src/ads-github-tools-0.3.4$ make
.../src/ads-github-tools-0.3.4$ make check
.../src/ads-github-tools-0.3.4$ make install
Note that the build also supports a "VPATH build", which allows building
out-of-tree, keeping the source code tree read-only and pristine. This is how
the author does it:
...
.../src$ gzip -dc ads-github-tools-0.3.4.gz | tar xf -
.../src$ chmod -R a-w ads-github-tools-0.3.4
.../src$
.../src$ mkdir ads-github-tools-0.3.4-BUILD
.../src$ cd ads-github-tools-0.3.4-BUILD
.../src/ads-github-tools-0.3.4-BUILD$ ../ads-github-tools-0.3.4/configure --prefix=/path/to/whatever
.../src/ads-github-tools-0.3.4-BUILD$ make
.../src/ads-github-tools-0.3.4-BUILD$ make check
.../src/ads-github-tools-0.3.4-BUILD$ make install
Building from Git
=================
All developers working on the 'ads-github-tools' project need to be using the
same versions of the Autotools programs in the toolchain. Currently (as of
2022-10), those versions are:
automake 1.16.3
autoconf 2.69
You can determine the versions in your PATH by invoking the respective tools
with the '--version' option:
$ automake --version
automake (GNU automake) 1.16.3
Copyright (C) 2020 Free Software Foundation, Inc.
License GPLv2+: GNU GPL version 2 or later <https://gnu.org/licenses/gpl-2.0.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Written by Tom Tromey <tromey@redhat.com>
and Alexandre Duret-Lutz <adl@gnu.org>.
$ autoconf --version
autoconf (GNU Autoconf) 2.69
Copyright (C) 2012 Free Software Foundation, Inc.
License GPLv3+/Autoconf: GNU GPL version 3 or later
<http://gnu.org/licenses/gpl.html>, <http://gnu.org/licenses/exceptions.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Written by David J. MacKenzie and Akim Demaille.
Check the ads-github-tools source out of git from the project's public GitHub
repository:
$ git clone https://github.com/salewski/ads-github-tools.git
$ cd ads-github-tools
You'll notice that there is a 'configure' script in the root directory, as
well as 'Makefile.in' files scattered throughout the tree. These files are all
generated by the GNU Autotools, and are checked into git to allow (in the
future) developers to configure the project upon cloning the git repository.
Upon a fresh clone, you should be able to just run 'configure'. However, if
you find that your working directory somehow has timestamps out of sync, then
you can force a regeneration of all of the GNU Autotools-generated files.
Pre-configuration: The 'bootstrap' script
$ pwd
.../ads-github-tools
$ ./bootstrap
The 'bootstrap' script is a thin wrapper around the 'autoreconf' program
(supplied by Autoconf), which itself invokes the GNU Autotools in the correct
order in such a way that it assumes all timestamps are invalid. This has the
effect of regenerating the autogenerated files with meaningful timestamps.
After you've run the 'bootstrap' script, you are ready to configure the
project for your host:
$ ./configure --prefix=/path/to/wherever
$ make
$ make check
You probably do not want to run 'make install' from your git working
directory. If you want to install ("for real") your newly hacked version of
the 'ads-github-tools' project, then create a distribution tarball and install
using that:
$ make distcheck
$ ls | grep ads-github-tools
ads-github-tools-0.3.5-snapshot.tar.gz
Note: It is not acceptable to simply invoke:
$ make dist
for a release of the 'ads-github-tools'. If the build does not pass the
'distcheck' verifications, the package is considered broken.
For new releases, the version of the project must be changed in the
'configure.ac' file (to remove the '-snapshot' token, etc.), and the
'bootstrap' script re-run to regenerate the GNU Autotools generated files
(such as the 'configure' program and all 'Makefile.in' files).
After a release is made, the version number should be incremented with the
constant '-snapshot' appended to it. Again, the 'boostrap' script should be
re-run to regenerate the GNU Autotools generated files.
For example, during the development of the code that will be released as
version 0.3.5, the version number specified in 'configure.ac' should be:
0.3.5-snapshot
This eliminates the possibility of producing artifacts labeled just '0.3.5'
which are not the final release.
When it comes time to do the release, the version number in 'configure.ac'
should be changed to remove the '-snapshot' suffix, and the 'bootstrap' script
rerun.
0.3.5
The GNU Autotools generated files should be checked into git, and the release
should be tagged. After the final release is tagged, the version number in
'configure.ac' should be bumped up for the next development cycle, and the
'bootstrap' script re-run.
0.3.6-snapshot