Blame


1 dd038bc6 2021-09-21 thomas.ad README.portable
2 dd038bc6 2021-09-21 thomas.ad ===============
3 dd038bc6 2021-09-21 thomas.ad
4 dd038bc6 2021-09-21 thomas.ad This is the portable version of got[1] (Game of Trees), using autotools to
5 e499844e 2022-03-03 thomas provide the library checks required for GoT's dependencies.
6 dd038bc6 2021-09-21 thomas.ad
7 e499844e 2022-03-03 thomas The following operating systems are supported:
8 dd038bc6 2021-09-21 thomas.ad
9 e499844e 2022-03-03 thomas * FreeBSD
10 e499844e 2022-03-03 thomas * NetBSD
11 b26177ad 2022-03-03 thomas * DragonFlyBSD
12 e499844e 2022-03-03 thomas * MacOS
13 e499844e 2022-03-03 thomas * Linux
14 e499844e 2022-03-03 thomas
15 dd038bc6 2021-09-21 thomas.ad DEPENDENCIES
16 dd038bc6 2021-09-21 thomas.ad ============
17 dd038bc6 2021-09-21 thomas.ad
18 e499844e 2022-03-03 thomas Linux:
19 dd038bc6 2021-09-21 thomas.ad
20 00ced238 2021-09-24 thomas * `libncurses` (for tog(1))
21 00ced238 2021-09-24 thomas * `libmd` (BSD's digest routines)
22 bd1cad3c 2022-04-30 thomas * `libbsd` (BSD's arc4random routines)
23 00ced238 2021-09-24 thomas * `libcrypto` (often via 'libssl-dev' for SHA1 routines)
24 00ced238 2021-09-24 thomas * `libuuid` (for UUID generation)
25 00ced238 2021-09-24 thomas * `libz` (for Z compression)
26 00ced238 2021-09-24 thomas * `pkg-config` (for searching libraries)
27 ebc794c1 2021-10-20 thomas * `bison` (for configuration file grammar)
28 60595c94 2022-07-16 thomas * `libevent` (for gotwebd)
29 dd038bc6 2021-09-21 thomas.ad
30 e499844e 2022-03-03 thomas FreeBSD:
31 e499844e 2022-03-03 thomas
32 e499844e 2022-03-03 thomas * `automake`
33 e499844e 2022-03-03 thomas * `pkgconf`
34 e8da6c41 2022-07-10 thomas * `GNU coreutils` (for running tests)
35 60595c94 2022-07-16 thomas * `libevent` (for gotwebd)
36 e499844e 2022-03-03 thomas
37 e499844e 2022-03-03 thomas NetBSD:
38 e499844e 2022-03-03 thomas
39 e499844e 2022-03-03 thomas * `automake`
40 e499844e 2022-03-03 thomas * `libuuid`
41 e499844e 2022-03-03 thomas * `ncuresesw`
42 e8da6c41 2022-07-10 thomas * `GNU coreutils` (for running tests)
43 60595c94 2022-07-16 thomas * `libevent` (for gotwebd)
44 e499844e 2022-03-03 thomas
45 b26177ad 2022-03-03 thomas DragonFlyBSD:
46 b26177ad 2022-03-03 thomas
47 b26177ad 2022-03-03 thomas * `automake`
48 b26177ad 2022-03-03 thomas * `pkgconf`
49 b26177ad 2022-03-03 thomas * `openssl`
50 e8da6c41 2022-07-10 thomas * `GNU coreutils` (for running tests)
51 60595c94 2022-07-16 thomas * `libevent` (for gotwebd)
52 b26177ad 2022-03-03 thomas
53 e499844e 2022-03-03 thomas Darwin (MacOS):
54 e499844e 2022-03-03 thomas
55 e499844e 2022-03-03 thomas * `automake`
56 e499844e 2022-03-03 thomas * `bison`
57 e499844e 2022-03-03 thomas * `pkg-config`
58 e499844e 2022-03-03 thomas * `ncurses`
59 e499844e 2022-03-03 thomas * `openssl`
60 e499844e 2022-03-03 thomas * `ossp-uuid`
61 e8da6c41 2022-07-10 thomas * `GNU coreutils` (for running tests)
62 60595c94 2022-07-16 thomas * `libevent` (for gotwebd)
63 e499844e 2022-03-03 thomas
64 d3f2ad5e 2021-09-21 thomas.ad TESTS (REGRESS)
65 d3f2ad5e 2021-09-21 thomas.ad ===============
66 d3f2ad5e 2021-09-21 thomas.ad
67 d3f2ad5e 2021-09-21 thomas.ad To run the test suite:
68 d3f2ad5e 2021-09-21 thomas.ad
69 00ced238 2021-09-24 thomas ```
70 d3f2ad5e 2021-09-21 thomas.ad $ make tests
71 00ced238 2021-09-24 thomas ```
72 d3f2ad5e 2021-09-21 thomas.ad
73 1317cd3a 2022-03-08 thomas NOTE: For Linux, you must have the jot(1) command which is typically in the
74 e8da6c41 2022-07-10 thomas `athena-jot` package, or similar. For non-linux systems (as mentioned above),
75 e8da6c41 2022-07-10 thomas GNU coreutils needs to be installed.
76 1317cd3a 2022-03-08 thomas
77 00ced238 2021-09-24 thomas NOTE: THIS ONLY WORKS AFTER `make install` DUE TO HOW PATHS TO LIBEXEC
78 d3f2ad5e 2021-09-21 thomas.ad HELPERS ARE HARD-CODED INTO THE BINARIES.
79 d3f2ad5e 2021-09-21 thomas.ad
80 dd038bc6 2021-09-21 thomas.ad INSTALLATION
81 dd038bc6 2021-09-21 thomas.ad ============
82 dd038bc6 2021-09-21 thomas.ad
83 00ced238 2021-09-24 thomas ```
84 72931428 2021-09-21 thomas.ad $ ./autogen.sh
85 dd038bc6 2021-09-21 thomas.ad $ ./configure && make
86 dd038bc6 2021-09-21 thomas.ad $ sudo make install
87 00ced238 2021-09-24 thomas ```
88 dd038bc6 2021-09-21 thomas.ad
89 00ced238 2021-09-24 thomas BRANCHES + SUBMITTING PATCHES
90 00ced238 2021-09-24 thomas =============================
91 00ced238 2021-09-24 thomas
92 00ced238 2021-09-24 thomas `got-portable` has two key branches:
93 00ced238 2021-09-24 thomas
94 00ced238 2021-09-24 thomas * `main` which tracks got upstream untainted.
95 2f4dd2c2 2021-09-27 thomas * `linux` which provides the portable version of GoT based from code on `main`
96 00ced238 2021-09-24 thomas
97 00ced238 2021-09-24 thomas Patches for portable code fixes should be based from the `linux` branch and
98 00ced238 2021-09-24 thomas sent to the mailing list for review [2] or sent to me directly (see CONTACT).
99 00ced238 2021-09-24 thomas
100 61702ba6 2022-07-19 thomas Portable-specific patches should have a shortlog in the form of:
101 61702ba6 2022-07-19 thomas
102 61702ba6 2022-07-19 thomas ```
103 61702ba6 2022-07-19 thomas portable: AREA: description
104 61702ba6 2022-07-19 thomas ```
105 61702ba6 2022-07-19 thomas
106 61702ba6 2022-07-19 thomas Where `AREA` relates to the change in question (for example, `regress`,
107 61702ba6 2022-07-19 thomas `libexec`, etc). In some cases, this can be omitted if it's a generic change.
108 61702ba6 2022-07-19 thomas
109 61702ba6 2022-07-19 thomas This helps to delineate `-portable` changes from upstream `got`.
110 61702ba6 2022-07-19 thomas
111 00ced238 2021-09-24 thomas The read-only Github repository also runs CI checks using Cirrus-CI on Linux
112 00ced238 2021-09-24 thomas and FreeBSD.
113 00ced238 2021-09-24 thomas
114 585fb430 2022-07-21 thomas SYNCING UPSTREAM CHANGES WITH PORTABLE
115 585fb430 2022-07-21 thomas ======================================
116 585fb430 2022-07-21 thomas
117 585fb430 2022-07-21 thomas The `-portable` GoT repository uses the following workflow:
118 585fb430 2022-07-21 thomas
119 585fb430 2022-07-21 thomas ```
120 585fb430 2022-07-21 thomas Github (gh) GoT (upstream)
121 585fb430 2022-07-21 thomas ^ ^
122 585fb430 2022-07-21 thomas | |
123 585fb430 2022-07-21 thomas | |
124 585fb430 2022-07-21 thomas | |
125 585fb430 2022-07-21 thomas | |
126 585fb430 2022-07-21 thomas +--------> GoT-portable <------+
127 585fb430 2022-07-21 thomas
128 585fb430 2022-07-21 thomas ```
129 585fb430 2022-07-21 thomas
130 585fb430 2022-07-21 thomas Here, `got-portable` is a clone of the `-portable` repository, locally on
131 585fb430 2022-07-21 thomas disk. There are two remotes set up within that repository, via `git-remote`:
132 585fb430 2022-07-21 thomas
133 585fb430 2022-07-21 thomas * `upstream` -- which points to the official GoT repository;
134 585fb430 2022-07-21 thomas * `gh` -- which points to the mirrored `-portable` repository so that CI can
135 585fb430 2022-07-21 thomas be run for cross-platform/test purposes [3]
136 585fb430 2022-07-21 thomas * `origin` -- our cloned copy from `-portable`
137 585fb430 2022-07-21 thomas
138 585fb430 2022-07-21 thomas Within the `-portable` repository are two key branches (there may be other
139 585fb430 2022-07-21 thomas topic branches which represent on-going work):
140 585fb430 2022-07-21 thomas
141 585fb430 2022-07-21 thomas * `main` -- this is the branch that tracks (without modification) those
142 585fb430 2022-07-21 thomas changes from `upstream`. This branch is continually reset to
143 585fb430 2022-07-21 thomas `upstream/main` whenever changes occur.
144 585fb430 2022-07-21 thomas
145 585fb430 2022-07-21 thomas * `linux` -- this is the *default* branch of the `-portable` repository which
146 585fb430 2022-07-21 thomas contains portable-specific changes to make `GoT` compile across different
147 585fb430 2022-07-21 thomas OSes.
148 585fb430 2022-07-21 thomas
149 585fb430 2022-07-21 thomas When updating `-portable` from upstream changes, the following actions happen:
150 585fb430 2022-07-21 thomas
151 585fb430 2022-07-21 thomas 1. Changes from `upstream` are fetched. If there are no new changes, there's
152 585fb430 2022-07-21 thomas nothing else to do.
153 585fb430 2022-07-21 thomas 2. Changes from `gh` are fetch so that the result can be pushed out to `gh`.
154 585fb430 2022-07-21 thomas 3. The difference between the local copy of `main` and `origin/main` is used
155 585fb430 2022-07-21 thomas to represent the set of commits which have *NOT* yet been merged to
156 585fb430 2022-07-21 thomas `-portable`.
157 585fb430 2022-07-21 thomas 4. A topic-branch called `syncup` is created from the HEAD of the `linux`
158 585fb430 2022-07-21 thomas branch to hold the to-be-cherry-picked commits from step 3.
159 585fb430 2022-07-21 thomas 5. These commits are then cherry-picked to the `syncup` branch.
160 585fb430 2022-07-21 thomas 6. If there's any conflicts, they must be resolved.
161 585fb430 2022-07-21 thomas 7. Once done, a sanity build is done in-situ to check there's nothing amiss.
162 585fb430 2022-07-21 thomas 8. If that succeeds, the `syncup` branch is merged to `linux` and pushed to
163 585fb430 2022-07-21 thomas `gh` for verification against CI.
164 585fb430 2022-07-21 thomas 9. If that fails, fixes continue and pushed up to `gh` as required.
165 585fb430 2022-07-21 thomas 10. Once happy, both the `main` and `linux` branches can be merged to `origin`.
166 585fb430 2022-07-21 thomas
167 585fb430 2022-07-21 thomas These steps are encapsulated in a script within `-portable`. [Link](../maintscripts/sync-upstream.sh)
168 585fb430 2022-07-21 thomas
169 ce0dfd3b 2022-07-21 thomas RELEASING A NEW VERSION
170 ce0dfd3b 2022-07-21 thomas =======================
171 ce0dfd3b 2022-07-21 thomas
172 ce0dfd3b 2022-07-21 thomas Release for `-portable` try and align as close to upstream GoT as much as
173 ce0dfd3b 2022-07-21 thomas possible, even on the same day where that can happen. That being said,
174 ce0dfd3b 2022-07-21 thomas sometimes a release of `-portable` might happen outside of that cadence, where
175 ce0dfd3b 2022-07-21 thomas a `-portable`-specific issue needs addressing, for example.
176 ce0dfd3b 2022-07-21 thomas
177 ce0dfd3b 2022-07-21 thomas Before creating a new release, check the version of GoT as found in
178 598139dd 2022-07-22 thomas `util/got-portable-ver.sh` -- as `GOT_PORTABLE_VER`:
179 ce0dfd3b 2022-07-21 thomas
180 ce0dfd3b 2022-07-21 thomas ```
181 598139dd 2022-07-22 thomas GOT_PORTABLE_VER=0.75
182 ce0dfd3b 2022-07-21 thomas
183 ce0dfd3b 2022-07-21 thomas ```
184 ce0dfd3b 2022-07-21 thomas
185 ce0dfd3b 2022-07-21 thomas Here, the *to be released* version of `got-portable` will be `0.75`.
186 ce0dfd3b 2022-07-21 thomas Typically, this version is incremented directly after a release, such that
187 ce0dfd3b 2022-07-21 thomas there's no need to change this value. The only exception would be if there
188 ce0dfd3b 2022-07-21 thomas were an out-of-band release to `-portable`. In such cases, that would take
189 ce0dfd3b 2022-07-21 thomas the form:
190 ce0dfd3b 2022-07-21 thomas
191 ce0dfd3b 2022-07-21 thomas ```
192 529beb87 2022-09-23 thomas 0.75.1
193 ce0dfd3b 2022-07-21 thomas ```
194 ce0dfd3b 2022-07-21 thomas
195 529beb87 2022-09-23 thomas Where the suffix of `1`, `2`, etc., can be used to denote any sub-releases
196 ce0dfd3b 2022-07-21 thomas from the `0.75` version.
197 ce0dfd3b 2022-07-21 thomas
198 05345ace 2022-09-10 thomas The variable `GOT_RELEASE` needs be changed to `yes` so that the
199 05345ace 2022-09-10 thomas GOT_PORTABLE_VER is asserted correctly.
200 05345ace 2022-09-10 thomas
201 ce0dfd3b 2022-07-21 thomas Once the version is verified, the following should be run from the `linux`
202 ce0dfd3b 2022-07-21 thomas branch -- and the repository should not have any outstanding modifications to
203 ce0dfd3b 2022-07-21 thomas the source:
204 ce0dfd3b 2022-07-21 thomas
205 ce0dfd3b 2022-07-21 thomas ```
206 ce0dfd3b 2022-07-21 thomas make clean ; ./autogen && ./configure && make distcheck
207 ce0dfd3b 2022-07-21 thomas ```
208 ce0dfd3b 2022-07-21 thomas
209 ce0dfd3b 2022-07-21 thomas If this succeeds, the tarball is in the CWD, as: `got-portable-VERSION.tar.gz`
210 ce0dfd3b 2022-07-21 thomas
211 ce0dfd3b 2022-07-21 thomas This can then be copied to the `got-www` repository and uploaded, along with
212 ce0dfd3b 2022-07-21 thomas changing a couple of HTML pages therein to represent the new released version.
213 ce0dfd3b 2022-07-21 thomas Additionally, the CHANGELOG file can be copied to the `got-www` and committed.
214 ce0dfd3b 2022-07-21 thomas
215 529beb87 2022-09-23 thomas Once all of that has been done, the repository should be tagged to indicate
216 529beb87 2022-09-23 thomas the release, hence:
217 529beb87 2022-09-23 thomas
218 529beb87 2022-09-23 thomas ```
219 529beb87 2022-09-23 thomas git tag -a 0.75
220 529beb87 2022-09-23 thomas ```
221 529beb87 2022-09-23 thomas
222 529beb87 2022-09-23 thomas This can then be pushed out to `gh` and `origin`.
223 529beb87 2022-09-23 thomas
224 529beb87 2022-09-23 thomas After that point, the version of `GOT_PORTABLE_VER` in
225 529beb87 2022-09-23 thomas `util/got-portable-ver.sh` should be changed to the next version, and
226 529beb87 2022-09-23 thomas `GOT_RELEASE` should be setg back to `no`.
227 529beb87 2022-09-23 thomas
228 dd038bc6 2021-09-21 thomas.ad TODO
229 dd038bc6 2021-09-21 thomas.ad ====
230 dd038bc6 2021-09-21 thomas.ad
231 dd038bc6 2021-09-21 thomas.ad configure.ac should start defining AC_ENABLE arguments to allow for
232 dd038bc6 2021-09-21 thomas.ad finer-grained control of where to search for includes/libraries, etc.
233 dd038bc6 2021-09-21 thomas.ad
234 dd038bc6 2021-09-21 thomas.ad CONTACT
235 dd038bc6 2021-09-21 thomas.ad =======
236 dd038bc6 2021-09-21 thomas.ad
237 585fb430 2022-07-21 thomas Thomas Adam <thomas@xteddy.org><br />
238 72931428 2021-09-21 thomas.ad thomas_adam (#gameoftrees on irc.libera.chat)
239 dd038bc6 2021-09-21 thomas.ad
240 585fb430 2022-07-21 thomas [1] https://gameoftrees.org<br />
241 6bfde126 2021-09-29 thomas [2] https://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long-full&extra=gameoftrees
242 585fb430 2022-07-21 thomas [3] https://github.com/ThomasAdam/got-portable