Blob


1 README.portable
2 ===============
4 **NOTE: This repository is read-only and is used only to mirror the
5 got-portable repository for CI purposes.**
7 This is the portable version of got[1] (Game of Trees), using autotools to
8 provide the library checks required for GoT's dependencies.
10 The following operating systems are supported:
12 * FreeBSD
13 * NetBSD
14 * DragonFlyBSD
15 * MacOS
16 * Linux
18 DEPENDENCIES
19 ============
21 Linux:
23 * `libncurses` (for tog(1))
24 * `libbsd` (BSD's arc4random routines)
25 * `libmd` (SHA256 routines)
26 * `libuuid` (for UUID generation)
27 * `libz` (for Z compression)
28 * `pkg-config` (for searching libraries)
29 * `bison` (for configuration file grammar)
31 FreeBSD:
33 * `automake`
34 * `pkgconf`
35 * `libevent` (for gotwebd)
37 NetBSD:
39 * `automake`
40 * `libuuid`
41 * `ncuresesw`
42 * `libevent` (for gotwebd)
44 DragonFlyBSD:
46 * `automake`
47 * `pkgconf`
48 * `openssl`
49 * `libevent` (for gotwebd)
51 Darwin (MacOS):
53 * `automake`
54 * `bison`
55 * `pkg-config`
56 * `ncurses`
57 * `openssl`
58 * `ossp-uuid`
59 * `libevent` (for gotwebd)
61 TESTS (REGRESS)
62 ===============
64 To run the test suite:
66 ```
67 $ make tests
68 ```
70 Dependencies
71 ============
73 * ed
75 NOTE: THIS ONLY WORKS AFTER `make install` DUE TO HOW PATHS TO LIBEXEC
76 HELPERS ARE HARD-CODED INTO THE BINARIES.
78 INSTALLATION
79 ============
81 ```
82 $ ./autogen.sh
83 $ ./configure && make
84 $ sudo make install
85 ```
87 INSTALLING AND PACKAGING GITWRAPPER
88 ===================================
90 The gotd server has an optional companion tool called gitwrapper.
92 A gotd server can be used without gitwrapper in the following cases:
94 1) The Git client's user account has gotsh configured as its login shell.
96 2) The Git client's user account sees gotsh installed under the names
97 git-receive-pack and git-upload-pack, and these appear in $PATH before
98 the corresponding Git binaries if Git is also installed. Setting up the
99 user's $PATH in this way can require the use of SetEnv in sshd_config.
101 The above cases can be too restrictive. For example, users who have regular
102 shell access to the system may expect to be able to serve Git repositories
103 from their home directories while also accessing repositories served by gotd.
105 Once gitwrapper has been installed correctly it provides an out-of-the box
106 experience where both gotd and Git "just work".
107 However, this will require coordination with the system's Git installation
108 and/or distribution package because the names of two specific Git programs
109 will be overlapping: git-upload-pack and git-receive-pack
111 If the gitwrapper tool will be used then it must replace git-receive-pack
112 and git-upload-pack in /usr/bin. This is usually achieved by replacing the
113 regular Git binaries in /usr/bin with symlinks to gitwrapper:
115 ```
116 -rwxr-xr-x 1 root root 1019928 Aug 24 00:16 /usr/bin/gitwrapper
117 lrwxrwxrwx 1 root root 10 Aug 20 12:40 /usr/bin/git-receive-pack -> gitwrapper
118 lrwxrwxrwx 1 root root 10 Aug 20 12:40 /usr/bin/git-upload-pack -> gitwrapper
119 ```
121 The Git binaries remain available in Git's libexec directory, which is set
122 when Git gets compiled. On Debian it defaults to /usr/lib/git-core.
123 This same path must be given to Got's configure script at build time to
124 allow gitwrapper to find Git's binaries:
126 ```
127 ./configure --with-gitwrapper-git-libexec-path=/usr/lib/git-core
128 ```
130 Once gitwrapper is found in /usr/bin under the names git-receive-pack and
131 git-upload-pack, any Git repositories listed in /etc/gotd.conf will be
132 automatically served by gotd, and any Git repositories not listed in
133 /etc/gotd.conf will be automatically served by regular Git's git-upload-pack
134 and git-receive-pack. The client's login shell or $PATH no longer matter,
135 and a peaceful co-existence of gotd and Git is possible.
137 We recommend that distribution packagers take appropriate steps to package
138 gitwrapper as a required dependency of gotd. It is also possible to install
139 gitwrapper without installing gotd. As long as /etc/gotd.conf does not exist
140 or no repositories are listed in /etc/gotd.conf there will be no visible
141 change in run-time behaviour for Git users since gitwrapper will simply run
142 the standard Git tools.
143 In the OpenBSD ports tree both the regular git package and the gotd package
144 are depending on gitwrapper, and the git package no longer installs the
145 git-receive-pack and git-upload-pack programs in /usr/local/bin.
147 BRANCHES + SUBMITTING PATCHES
148 =============================
150 `got-portable` has two key branches:
152 * `main` which tracks got upstream untainted.
153 * `portable` which provides the portable version of GoT based from code on `main`
155 Patches for portable code fixes should be based from the `portable` branch and
156 sent to the mailing list for review [2] or sent to me directly (see CONTACT).
158 Portable-specific patches should have a shortlog in the form of:
160 ```
161 portable: AREA: description
162 ```
164 Where `AREA` relates to the change in question (for example, `regress`,
165 `libexec`, etc). In some cases, this can be omitted if it's a generic change.
167 This helps to delineate `-portable` changes from upstream `got`.
169 The read-only Github repository also runs CI checks using Cirrus-CI on Linux
170 and FreeBSD.
172 SYNCING UPSTREAM CHANGES WITH PORTABLE
173 ======================================
175 The `-portable` GoT repository uses the following workflow:
177 ```
178 Github (gh) GoT (upstream)
179 ^ ^
180 | |
181 | |
182 | |
183 | |
184 +--------> GoT-portable <------+
186 ```
188 Here, `got-portable` is a clone of the `-portable` repository, locally on
189 disk. There are two remotes set up within that repository, via `git-remote`:
191 * `upstream` -- which points to the official GoT repository;
192 * `gh` -- which points to the mirrored `-portable` repository so that CI can
193 be run for cross-platform/test purposes [3]
194 * `origin` -- our cloned copy from `-portable`
196 Within the `-portable` repository are two key branches (there may be other
197 topic branches which represent on-going work):
199 * `main` -- this is the branch that tracks (without modification) those
200 changes from `upstream`. This branch is continually reset to
201 `upstream/main` whenever changes occur.
203 * `portable` -- this is the *default* branch of the `-portable` repository which
204 contains portable-specific changes to make `GoT` compile across different
205 OSes.
207 When updating `-portable` from upstream changes, the following actions happen:
209 1. Changes from `upstream` are fetched. If there are no new changes, there's
210 nothing else to do.
211 2. Changes from `gh` are fetch so that the result can be pushed out to `gh`.
212 3. The difference between the local copy of `main` and `origin/main` is used
213 to represent the set of commits which have *NOT* yet been merged to
214 `-portable`.
215 4. A topic-branch called `syncup` is created from the HEAD of the `portable`
216 branch to hold the to-be-cherry-picked commits from step 3.
217 5. These commits are then cherry-picked to the `syncup` branch.
218 6. If there's any conflicts, they must be resolved.
219 7. Once done, a sanity build is done in-situ to check there's nothing amiss.
220 8. If that succeeds, the `syncup` branch is merged to `portable` and pushed to
221 `gh` for verification against CI.
222 9. If that fails, fixes continue and pushed up to `gh` as required.
223 10. Once happy, both the `main` and `portable` branches can be merged to `origin`.
225 These steps are encapsulated in a script within `-portable`. [Link](../maintscripts/sync-upstream.sh)
227 RELEASING A NEW VERSION
228 =======================
230 Release for `-portable` try and align as close to upstream GoT as much as
231 possible, even on the same day where that can happen. That being said,
232 sometimes a release of `-portable` might happen outside of that cadence, where
233 a `-portable`-specific issue needs addressing, for example.
235 Before creating a new release, check the version of GoT as found in
236 `util/got-portable-ver.sh` -- as `GOT_PORTABLE_VER`:
238 ```
239 GOT_PORTABLE_VER=0.75
241 ```
243 Here, the *to be released* version of `got-portable` will be `0.75`.
244 Typically, this version is incremented directly after a release, such that
245 there's no need to change this value. The only exception would be if there
246 were an out-of-band release to `-portable`. In such cases, that would take
247 the form:
249 ```
250 0.75.1
251 ```
253 Where the suffix of `1`, `2`, etc., can be used to denote any sub-releases
254 from the `0.75` version.
256 The variable `GOT_RELEASE` needs be changed to `yes` so that the
257 GOT_PORTABLE_VER is asserted correctly.
259 Once the version is verified, the following should be run from the `portable`
260 branch -- and the repository should not have any outstanding modifications to
261 the source:
263 ```
264 make clean ; ./autogen && ./configure && make distcheck
265 ```
267 If this succeeds, the tarball is in the CWD, as: `got-portable-VERSION.tar.gz`
269 This can then be copied to the `got-www` repository and uploaded, along with
270 changing a couple of HTML pages therein to represent the new released version.
271 Additionally, the CHANGELOG file can be copied to the `got-www` and committed.
273 Once all of that has been done, the repository should be tagged to indicate
274 the release, hence:
276 ```
277 git tag -a 0.75
278 ```
280 This can then be pushed out to `gh` and `origin`.
282 After that point, the version of `GOT_PORTABLE_VER` in
283 `util/got-portable-ver.sh` should be changed to the next version, and
284 `GOT_RELEASE` should be setg back to `no`.
286 TODO
287 ====
289 This port is incomplete in that only got(1) and tog(1) have been ported.
290 gotweb has yet to be ported.
292 configure.ac should start defining AC_ENABLE arguments to allow for
293 finer-grained control of where to search for includes/libraries, etc.
295 CONTACT
296 =======
298 Thomas Adam <thomas@xteddy.org><br />
299 thomas_adam (#gameoftrees on irc.libera.chat)
301 [1] https://gameoftrees.org<br />
302 [2] https://lists.openbsd.org/cgi-bin/mj_wwwusr?user=&passw=&func=lists-long-full&extra=gameoftrees<br />
303 [3] https://github.com/ThomasAdam/got-portable