README.md (2678B)
1 gitout 2 ====== 3 4 Gitout is a static git repository builder designed to be output-compatible with 5 the excellent `stagit` tool, but adds support for multiple output formats in the 6 same binary: html (-H) and gopher (-G). 7 8 Early support for Gemini is available on the `gemini` branch. 9 10 Prerequisites 11 ------------- 12 13 To build, the following tooling must be installed on the system: 14 * [gn](https://gn.googlesource.com/gn) 15 * [ninja](https://github.com/ninja-build/ninja) 16 * A [clang](http://clang.llvm.org) toolchain 17 18 To build and run, the following libraries must be installed on the system: 19 * [libgit2](https://libgit2.org) 20 21 22 Obtaining the source 23 -------------------- 24 25 First, clone the repo. Then, initialise and fetch git submodules: 26 27 # Initialise local configuration file. 28 git submodule init 29 30 # Fetch data from the buildroot submodule. 31 git submodule update 32 33 34 Updating the gn buildroot 35 ------------------------- 36 37 To update the git submodules to a newer commit, simply run: 38 39 git submodule update --remote 40 41 42 Building and running 43 -------------------- 44 45 First, edit `.gn` as necessary to set the `system_include_dirs` and 46 `system_lib_dirs` for your system. 47 48 Next, generate the ninja build files under the `out` directory: 49 50 gn gen --args=is_debug=true out/debug 51 gn gen --args=is_debug=false out/release 52 53 54 ### Unit tests 55 56 To build and run the unit tests, run: 57 58 gn gen --args=is_debug=true out/debug 59 ninja -C out/debug :gitout_tests 60 ./out/debug/gitout_tests 61 62 or 63 64 make test 65 66 67 ### Executable release-mode binary 68 69 To build and run the binary: 70 71 gn gen --args=is_debug=false out/release 72 ninja -C out/release :gitout :gitout_index 73 ./out/release/gitout 74 ./out/release/gitout_index 75 76 or 77 78 make release 79 ./out/release/gitout 80 ./out/release/gitout_index 81 82 83 Background 84 ---------- 85 86 Gitout started as a set of small refactorings of stagit written primarily to 87 separate git logic from formatting logic in order to experiment with merging 88 gopher support into the same tool, and eventually add gemini support. Things got 89 a bit out of hand and I'm embarrassed to say the code now reads a bit more like 90 Enterprise Stagit. 91 92 In my defence, the final compiled binary size is still small; under 60 kB on 93 FreeBSD. It would be worthwhile trying to simplify the code a bit, now that 94 things are separated out and the formatters are now effectively pluggable. 95 96 97 Patches welcome 98 --------------- 99 100 Patches are more than welcome via [`git send-email`](https://git-send-email.io): 101 ``` 102 $ git config sendemail.to "Chris Bracken <chris@bracken.jp>" 103 $ git send-email ... 104 ``` 105 or alternatively, generate the patches via `git format-patch` and email them 106 manually.