1 dd038bc6 2021-09-21 thomas.ad README.portable
2 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.
7 e499844e 2022-03-03 thomas The following operating systems are supported:
11 b26177ad 2022-03-03 thomas * DragonFlyBSD
15 dd038bc6 2021-09-21 thomas.ad DEPENDENCIES
16 dd038bc6 2021-09-21 thomas.ad ============
18 62e037f1 2024-04-26 thomas.ad Note that the names of these libraries are indicative only; the names might
23 00ced238 2021-09-24 thomas * `libncurses` (for tog(1))
24 bd1cad3c 2022-04-30 thomas * `libbsd` (BSD's arc4random routines)
25 5007bd0d 2023-04-14 thomas * `libmd` (SHA256 routines)
26 00ced238 2021-09-24 thomas * `libuuid` (for UUID generation)
27 00ced238 2021-09-24 thomas * `libz` (for Z compression)
28 00ced238 2021-09-24 thomas * `pkg-config` (for searching libraries)
29 ebc794c1 2021-10-20 thomas * `bison` (for configuration file grammar)
30 60595c94 2022-07-16 thomas * `libevent` (for gotwebd)
31 62e037f1 2024-04-26 thomas.ad * `libtls` (may be known as `libretls`)
35 e499844e 2022-03-03 thomas * `automake`
36 e499844e 2022-03-03 thomas * `pkgconf`
37 62e037f1 2024-04-26 thomas.ad * `libretls`
38 60595c94 2022-07-16 thomas * `libevent` (for gotwebd)
42 e499844e 2022-03-03 thomas * `automake`
43 e499844e 2022-03-03 thomas * `libuuid`
44 e499844e 2022-03-03 thomas * `ncuresesw`
45 60595c94 2022-07-16 thomas * `libevent` (for gotwebd)
46 62e037f1 2024-04-26 thomas.ad * `libretls`
48 b26177ad 2022-03-03 thomas DragonFlyBSD:
50 b26177ad 2022-03-03 thomas * `automake`
51 b26177ad 2022-03-03 thomas * `pkgconf`
52 b26177ad 2022-03-03 thomas * `openssl`
53 60595c94 2022-07-16 thomas * `libevent` (for gotwebd)
54 62e037f1 2024-04-26 thomas.ad * `libretls`
56 e499844e 2022-03-03 thomas Darwin (MacOS):
58 e499844e 2022-03-03 thomas * `automake`
60 e499844e 2022-03-03 thomas * `pkg-config`
61 e499844e 2022-03-03 thomas * `ncurses`
62 e499844e 2022-03-03 thomas * `openssl`
63 e499844e 2022-03-03 thomas * `ossp-uuid`
64 60595c94 2022-07-16 thomas * `libevent` (for gotwebd)
65 62e037f1 2024-04-26 thomas.ad * `libretls`
67 d3f2ad5e 2021-09-21 thomas.ad TESTS (REGRESS)
68 d3f2ad5e 2021-09-21 thomas.ad ===============
70 d3f2ad5e 2021-09-21 thomas.ad To run the test suite:
73 d3f2ad5e 2021-09-21 thomas.ad $ make tests
76 d469c4c2 2025-01-03 stsp The tests depend on git and the HTTP::Daemon Perl module.
78 d469c4c2 2025-01-03 stsp Got may have to be installed system-wide before the tests will run
79 d469c4c2 2025-01-03 stsp successfully because paths to helper programs, such as got-read-pack,
80 d469c4c2 2025-01-03 stsp are hard-coded in user-facing binaries, such as got and tog.
82 d469c4c2 2025-01-03 stsp Operations such as clone and send which use the network will be trying to
83 d469c4c2 2025-01-03 stsp connect to 127.0.0.1 over ssh, as the same user who invoked 'make tests'.
84 d469c4c2 2025-01-03 stsp The command 'ssh 127.0.0.1' must succeed without any interactive prompting.
85 d469c4c2 2025-01-03 stsp The host key may need to be manually accepted once before running tests.
86 d469c4c2 2025-01-03 stsp An SSH key can be installed in ~/.ssh/authorized_keys for authentication.
88 d469c4c2 2025-01-03 stsp The OpenBSD version of Got also has tests for gotd and gotwebd.
89 d469c4c2 2025-01-03 stsp These tests cannot be run in -portable yet.
91 d469c4c2 2025-01-03 stsp There are environment variables which control some test parameters:
93 d469c4c2 2025-01-03 stsp GOT_TEST_PACK=1 will force tests to use pack files instead of loose
94 d469c4c2 2025-01-03 stsp objects. GOT_TEST_PACK=ref-delta will force use of pack files with
95 d469c4c2 2025-01-03 stsp ref-deltas rather than offset-deltas.
97 d469c4c2 2025-01-03 stsp GOT_TEST_ALGO=sha256 will run tests with sha256 repositories.
99 d469c4c2 2025-01-03 stsp GOT_TEST_ROOT can be set to a path where temporary test data gets stored.
100 d469c4c2 2025-01-03 stsp This defaults to /tmp.
102 5713faaf 2023-03-09 thomas Dependencies
103 5713faaf 2023-03-09 thomas ============
107 00ced238 2021-09-24 thomas NOTE: THIS ONLY WORKS AFTER `make install` DUE TO HOW PATHS TO LIBEXEC
108 d3f2ad5e 2021-09-21 thomas.ad HELPERS ARE HARD-CODED INTO THE BINARIES.
110 dd038bc6 2021-09-21 thomas.ad INSTALLATION
111 dd038bc6 2021-09-21 thomas.ad ============
114 72931428 2021-09-21 thomas.ad $ ./autogen.sh
115 dd038bc6 2021-09-21 thomas.ad $ ./configure && make
116 dd038bc6 2021-09-21 thomas.ad $ sudo make install
119 0edd41e7 2023-08-29 thomas INSTALLING AND PACKAGING GITWRAPPER
120 0edd41e7 2023-08-29 thomas ===================================
122 0edd41e7 2023-08-29 thomas The gotd server has an optional companion tool called gitwrapper.
124 0edd41e7 2023-08-29 thomas A gotd server can be used without gitwrapper in the following cases:
126 0edd41e7 2023-08-29 thomas 1) The Git client's user account has gotsh configured as its login shell.
128 0edd41e7 2023-08-29 thomas 2) The Git client's user account sees gotsh installed under the names
129 0edd41e7 2023-08-29 thomas git-receive-pack and git-upload-pack, and these appear in $PATH before
130 0edd41e7 2023-08-29 thomas the corresponding Git binaries if Git is also installed. Setting up the
131 0edd41e7 2023-08-29 thomas user's $PATH in this way can require the use of SetEnv in sshd_config.
133 0edd41e7 2023-08-29 thomas The above cases can be too restrictive. For example, users who have regular
134 0edd41e7 2023-08-29 thomas shell access to the system may expect to be able to serve Git repositories
135 0edd41e7 2023-08-29 thomas from their home directories while also accessing repositories served by gotd.
137 0edd41e7 2023-08-29 thomas Once gitwrapper has been installed correctly it provides an out-of-the box
138 0edd41e7 2023-08-29 thomas experience where both gotd and Git "just work".
139 0edd41e7 2023-08-29 thomas However, this will require coordination with the system's Git installation
140 0edd41e7 2023-08-29 thomas and/or distribution package because the names of two specific Git programs
141 0edd41e7 2023-08-29 thomas will be overlapping: git-upload-pack and git-receive-pack
143 0edd41e7 2023-08-29 thomas If the gitwrapper tool will be used then it must replace git-receive-pack
144 0edd41e7 2023-08-29 thomas and git-upload-pack in /usr/bin. This is usually achieved by replacing the
145 0edd41e7 2023-08-29 thomas regular Git binaries in /usr/bin with symlinks to gitwrapper:
148 0edd41e7 2023-08-29 thomas -rwxr-xr-x 1 root root 1019928 Aug 24 00:16 /usr/bin/gitwrapper
149 0edd41e7 2023-08-29 thomas lrwxrwxrwx 1 root root 10 Aug 20 12:40 /usr/bin/git-receive-pack -> gitwrapper
150 0edd41e7 2023-08-29 thomas lrwxrwxrwx 1 root root 10 Aug 20 12:40 /usr/bin/git-upload-pack -> gitwrapper
153 0edd41e7 2023-08-29 thomas The Git binaries remain available in Git's libexec directory, which is set
154 0edd41e7 2023-08-29 thomas when Git gets compiled. On Debian it defaults to /usr/lib/git-core.
155 0edd41e7 2023-08-29 thomas This same path must be given to Got's configure script at build time to
156 0edd41e7 2023-08-29 thomas allow gitwrapper to find Git's binaries:
159 0edd41e7 2023-08-29 thomas ./configure --with-gitwrapper-git-libexec-path=/usr/lib/git-core
162 0edd41e7 2023-08-29 thomas Once gitwrapper is found in /usr/bin under the names git-receive-pack and
163 0edd41e7 2023-08-29 thomas git-upload-pack, any Git repositories listed in /etc/gotd.conf will be
164 0edd41e7 2023-08-29 thomas automatically served by gotd, and any Git repositories not listed in
165 0edd41e7 2023-08-29 thomas /etc/gotd.conf will be automatically served by regular Git's git-upload-pack
166 0edd41e7 2023-08-29 thomas and git-receive-pack. The client's login shell or $PATH no longer matter,
167 0edd41e7 2023-08-29 thomas and a peaceful co-existence of gotd and Git is possible.
169 0edd41e7 2023-08-29 thomas We recommend that distribution packagers take appropriate steps to package
170 0edd41e7 2023-08-29 thomas gitwrapper as a required dependency of gotd. It is also possible to install
171 0edd41e7 2023-08-29 thomas gitwrapper without installing gotd. As long as /etc/gotd.conf does not exist
172 0edd41e7 2023-08-29 thomas or no repositories are listed in /etc/gotd.conf there will be no visible
173 0edd41e7 2023-08-29 thomas change in run-time behaviour for Git users since gitwrapper will simply run
174 0edd41e7 2023-08-29 thomas the standard Git tools.
175 0edd41e7 2023-08-29 thomas In the OpenBSD ports tree both the regular git package and the gotd package
176 0edd41e7 2023-08-29 thomas are depending on gitwrapper, and the git package no longer installs the
177 0edd41e7 2023-08-29 thomas git-receive-pack and git-upload-pack programs in /usr/local/bin.
179 00ced238 2021-09-24 thomas BRANCHES + SUBMITTING PATCHES
180 00ced238 2021-09-24 thomas =============================
182 00ced238 2021-09-24 thomas `got-portable` has two key branches:
184 00ced238 2021-09-24 thomas * `main` which tracks got upstream untainted.
185 04dafe6d 2023-03-10 thomas * `portable` which provides the portable version of GoT based from code on `main`
187 04dafe6d 2023-03-10 thomas Patches for portable code fixes should be based from the `portable` branch and
188 00ced238 2021-09-24 thomas sent to the mailing list for review [2] or sent to me directly (see CONTACT).
190 61702ba6 2022-07-19 thomas Portable-specific patches should have a shortlog in the form of:
193 61702ba6 2022-07-19 thomas portable: AREA: description
196 61702ba6 2022-07-19 thomas Where `AREA` relates to the change in question (for example, `regress`,
197 61702ba6 2022-07-19 thomas `libexec`, etc). In some cases, this can be omitted if it's a generic change.
199 61702ba6 2022-07-19 thomas This helps to delineate `-portable` changes from upstream `got`.
201 00ced238 2021-09-24 thomas The read-only Github repository also runs CI checks using Cirrus-CI on Linux
202 00ced238 2021-09-24 thomas and FreeBSD.
204 585fb430 2022-07-21 thomas SYNCING UPSTREAM CHANGES WITH PORTABLE
205 585fb430 2022-07-21 thomas ======================================
207 585fb430 2022-07-21 thomas The `-portable` GoT repository uses the following workflow:
210 585fb430 2022-07-21 thomas Github (gh) GoT (upstream)
216 585fb430 2022-07-21 thomas +--------> GoT-portable <------+
220 585fb430 2022-07-21 thomas Here, `got-portable` is a clone of the `-portable` repository, locally on
221 585fb430 2022-07-21 thomas disk. There are two remotes set up within that repository, via `git-remote`:
223 585fb430 2022-07-21 thomas * `upstream` -- which points to the official GoT repository;
224 585fb430 2022-07-21 thomas * `gh` -- which points to the mirrored `-portable` repository so that CI can
225 585fb430 2022-07-21 thomas be run for cross-platform/test purposes [3]
226 585fb430 2022-07-21 thomas * `origin` -- our cloned copy from `-portable`
228 585fb430 2022-07-21 thomas Within the `-portable` repository are two key branches (there may be other
229 585fb430 2022-07-21 thomas topic branches which represent on-going work):
231 585fb430 2022-07-21 thomas * `main` -- this is the branch that tracks (without modification) those
232 585fb430 2022-07-21 thomas changes from `upstream`. This branch is continually reset to
233 585fb430 2022-07-21 thomas `upstream/main` whenever changes occur.
235 04dafe6d 2023-03-10 thomas * `portable` -- this is the *default* branch of the `-portable` repository which
236 585fb430 2022-07-21 thomas contains portable-specific changes to make `GoT` compile across different
239 585fb430 2022-07-21 thomas When updating `-portable` from upstream changes, the following actions happen:
241 585fb430 2022-07-21 thomas 1. Changes from `upstream` are fetched. If there are no new changes, there's
242 585fb430 2022-07-21 thomas nothing else to do.
243 585fb430 2022-07-21 thomas 2. Changes from `gh` are fetch so that the result can be pushed out to `gh`.
244 585fb430 2022-07-21 thomas 3. The difference between the local copy of `main` and `origin/main` is used
245 585fb430 2022-07-21 thomas to represent the set of commits which have *NOT* yet been merged to
246 585fb430 2022-07-21 thomas `-portable`.
247 04dafe6d 2023-03-10 thomas 4. A topic-branch called `syncup` is created from the HEAD of the `portable`
248 585fb430 2022-07-21 thomas branch to hold the to-be-cherry-picked commits from step 3.
249 585fb430 2022-07-21 thomas 5. These commits are then cherry-picked to the `syncup` branch.
250 585fb430 2022-07-21 thomas 6. If there's any conflicts, they must be resolved.
251 585fb430 2022-07-21 thomas 7. Once done, a sanity build is done in-situ to check there's nothing amiss.
252 04dafe6d 2023-03-10 thomas 8. If that succeeds, the `syncup` branch is merged to `portable` and pushed to
253 585fb430 2022-07-21 thomas `gh` for verification against CI.
254 585fb430 2022-07-21 thomas 9. If that fails, fixes continue and pushed up to `gh` as required.
255 04dafe6d 2023-03-10 thomas 10. Once happy, both the `main` and `portable` branches can be merged to `origin`.
257 585fb430 2022-07-21 thomas These steps are encapsulated in a script within `-portable`. [Link](../maintscripts/sync-upstream.sh)
259 ce0dfd3b 2022-07-21 thomas RELEASING A NEW VERSION
260 ce0dfd3b 2022-07-21 thomas =======================
262 ce0dfd3b 2022-07-21 thomas Release for `-portable` try and align as close to upstream GoT as much as
263 ce0dfd3b 2022-07-21 thomas possible, even on the same day where that can happen. That being said,
264 ce0dfd3b 2022-07-21 thomas sometimes a release of `-portable` might happen outside of that cadence, where
265 ce0dfd3b 2022-07-21 thomas a `-portable`-specific issue needs addressing, for example.
267 ce0dfd3b 2022-07-21 thomas Before creating a new release, check the version of GoT as found in
268 598139dd 2022-07-22 thomas `util/got-portable-ver.sh` -- as `GOT_PORTABLE_VER`:
271 598139dd 2022-07-22 thomas GOT_PORTABLE_VER=0.75
275 ce0dfd3b 2022-07-21 thomas Here, the *to be released* version of `got-portable` will be `0.75`.
276 ce0dfd3b 2022-07-21 thomas Typically, this version is incremented directly after a release, such that
277 ce0dfd3b 2022-07-21 thomas there's no need to change this value. The only exception would be if there
278 ce0dfd3b 2022-07-21 thomas were an out-of-band release to `-portable`. In such cases, that would take
279 ce0dfd3b 2022-07-21 thomas the form:
285 529beb87 2022-09-23 thomas Where the suffix of `1`, `2`, etc., can be used to denote any sub-releases
286 ce0dfd3b 2022-07-21 thomas from the `0.75` version.
288 05345ace 2022-09-10 thomas The variable `GOT_RELEASE` needs be changed to `yes` so that the
289 05345ace 2022-09-10 thomas GOT_PORTABLE_VER is asserted correctly.
291 04dafe6d 2023-03-10 thomas Once the version is verified, the following should be run from the `portable`
292 ce0dfd3b 2022-07-21 thomas branch -- and the repository should not have any outstanding modifications to
293 ce0dfd3b 2022-07-21 thomas the source:
296 ce0dfd3b 2022-07-21 thomas make clean ; ./autogen && ./configure && make distcheck
299 ce0dfd3b 2022-07-21 thomas If this succeeds, the tarball is in the CWD, as: `got-portable-VERSION.tar.gz`
301 ce0dfd3b 2022-07-21 thomas This can then be copied to the `got-www` repository and uploaded, along with
302 ce0dfd3b 2022-07-21 thomas changing a couple of HTML pages therein to represent the new released version.
303 ce0dfd3b 2022-07-21 thomas Additionally, the CHANGELOG file can be copied to the `got-www` and committed.
305 529beb87 2022-09-23 thomas Once all of that has been done, the repository should be tagged to indicate
306 529beb87 2022-09-23 thomas the release, hence:
309 529beb87 2022-09-23 thomas git tag -a 0.75
312 529beb87 2022-09-23 thomas This can then be pushed out to `gh` and `origin`.
314 529beb87 2022-09-23 thomas After that point, the version of `GOT_PORTABLE_VER` in
315 529beb87 2022-09-23 thomas `util/got-portable-ver.sh` should be changed to the next version, and
316 529beb87 2022-09-23 thomas `GOT_RELEASE` should be setg back to `no`.
321 415a43bb 2023-02-25 thomas * configure.ac should start defining AC_ENABLE arguments to allow for
322 415a43bb 2023-02-25 thomas finer-grained control of where to search for includes/libraries, etc.
323 415a43bb 2023-02-25 thomas * review the compat/ code. Some of those functions are probably picked up in
324 415a43bb 2023-02-25 thomas libbsd, so we should drop such implementations from compat/ where there's
325 415a43bb 2023-02-25 thomas overlap between libbsd and what's natively available.
327 dd038bc6 2021-09-21 thomas.ad CONTACT
328 dd038bc6 2021-09-21 thomas.ad =======
330 585fb430 2022-07-21 thomas Thomas Adam <thomas@xteddy.org><br />
331 72931428 2021-09-21 thomas.ad thomas_adam (#gameoftrees on irc.libera.chat)
333 585fb430 2022-07-21 thomas [1] https://gameoftrees.org<br />
334 6bfde126 2021-09-29 thomas [2] https://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long-full&extra=gameoftrees
335 585fb430 2022-07-21 thomas [3] https://github.com/ThomasAdam/got-portable
