README.source (4470B)
1 Building the kych package 2 ========================= 3 4 Binary-only builds from a git checkout, which is how this package is produced: 5 6 ./debian/stamp-version.sh 7 dpkg-buildpackage -b -uc -us 8 9 The first step rewrites debian/changelog with the version reported by 10 scripts/get_version.sh -- the same "git describe --tags" logic the other GNU 11 Taler repositories use -- because dpkg takes the package version from the 12 changelog and from nowhere else. It is idempotent, and it falls back to 13 0.0.0-<commits>-g<hash> while this repository still has no release tag. 14 15 Notes for whoever touches this next 16 ----------------------------------- 17 18 * No debian/source/format is present, so the source format is the default 1.0. 19 This matches the other Rust packages in the GNU Taler tree (robocop, 20 taler-rust) and is fine for the "-b" builds above; producing a source package 21 would need a format decision and an orig tarball first. 22 23 * The crate has one path dependency, ../taler-config, which is the vendored 24 copy of the GNU Taler configuration parser, logging setup and socket-binding 25 logic; see taler-config/README for what it is and how to re-sync it. Cargo 26 builds it as part of the main crate, so it needs no separate step -- but 27 "debian/rules clean" has to remove its target/ as well. 28 29 * The build is not offline: cargo fetches crates from crates.io, into 30 debian/cargo (CARGO_HOME) so that nothing outside the build tree is written. 31 There is no Cargo.lock in the repository, so builds are not reproducible 32 across dependency releases either. Both would have to be fixed before this 33 could go to the Debian archive; neither matters for the .deb builds we do. 34 35 * Man pages are generated at build time by sphinx-build from 36 documentation/taler-docs/manpages/, the same reStructuredText that the 37 taler-docs repository renders for the website, so there is one source for 38 both. The configuration used here is documentation/sphinx-man/conf.py, a 39 minimal file holding little more than the man_pages entries; taler-docs has 40 its own conf.py with a long list of extensions, which is why we do not reuse 41 it. The NAME line of each page comes from the man_pages entry, not from the 42 document, which is why each source wraps its own "Name" section in 43 ".. only:: html". 44 45 Consequences worth knowing: the man page sources may only use directives that 46 plain Sphinx understands (they currently use "only", "code-block", "note" and 47 "warning"), and the build prints "document isn't included in any toctree" for 48 two of the three pages. That warning is expected here - the toctree lives in 49 taler-docs - and cannot be suppressed, as it carries no warning type. 50 51 * The daemon serves its QR-code JavaScript from a path relative to the process 52 working directory, so debian/kych.service sets WorkingDirectory to 53 /usr/share/kych, where debian/kych.install puts js/. Changing either without 54 the other breaks the /authorize page. 55 56 Upstreaming the man pages 57 ------------------------- 58 59 documentation/taler-docs/manpages/ is copied into the taler-docs checkout as 60 described in documentation/taler-docs/README. Sphinx there will not build a 61 man page unless it is also listed in taler-docs/conf.py, so the three entries 62 from documentation/sphinx-man/conf.py have to be added to the man_pages list 63 there as well, with a "manpages/" prefix on the first field: 64 65 ("manpages/kych-oauth2-gateway.1", "kych-oauth2-gateway", 66 "OAuth 2.0 gateway for SWIYU credential verification", 67 ["GNU Taler contributors"], 1), 68 ("manpages/kych-client-management.1", "kych-client-management", 69 "manage OAuth 2.0 clients of the KyCH gateway", 70 ["GNU Taler contributors"], 1), 71 ("manpages/kych.conf.5", "kych.conf", 72 "configuration file of the KyCH OAuth 2.0 gateway", 73 ["GNU Taler contributors"], 5), 74 75 Keep the two lists identical, or the same source will produce a different NAME 76 line depending on who builds it. 77 78 taler-docs also carries shared fragments that kych.conf.5.rst now duplicates in 79 its own words: frags/common-conf-syntax.rst for the file format and 80 manpages/frags/common-serve-options.rst for SERVE/BIND_TO/PORT/UNIXPATH, both 81 pulled in with ".. include::" by the sibling components. Switching to them 82 would be the right move once the page lives in taler-docs -- but it cannot 83 happen here, because the fragments are not in this repository and the Debian 84 build renders these sources standalone. 85 86 -- Taler Systems SA <deb@taler.net>