aboutsummaryrefslogtreecommitdiffstats
path: root/doc/build.md
diff options
context:
space:
mode:
authorGuilhem Moulin <guilhem@fripost.org>2019-07-05 01:03:36 +0200
committerGuilhem Moulin <guilhem@fripost.org>2019-07-05 03:32:01 +0200
commit25f1dbdf54947bd6bbce653bc64f6c45b2473792 (patch)
treeeb5a21d1a528502845da6b987d4431bd04a4a5bd /doc/build.md
parentc4abd6128c3ca5471afc84225533a958ce273875 (diff)
Refactor documentation.
In particular, move manpages to the 'doc' directory, and generate HTML documentation with `make html`.
Diffstat (limited to 'doc/build.md')
-rw-r--r--doc/build.md99
1 files changed, 99 insertions, 0 deletions
diff --git a/doc/build.md b/doc/build.md
new file mode 100644
index 0000000..38d1bfb
--- /dev/null
+++ b/doc/build.md
@@ -0,0 +1,99 @@
+% Build instructions
+% Guilhem Moulin <guilhem@fripost.org>
+
+On Debian 9 (codename *Stretch*) and later, installing [`interimap`(1)]
+is a single command away:
+
+ $ apt-get install interimap
+
+This document is for those who are running other systems, and/or who
+wish to install from [source](https://git.guilhem.org/interimap).
+
+
+Dependencies
+============
+
+[`interimap`(1)](interimap.1.html) depends on Perl ≥5.20 and the
+following Perl modules:
+
+ * [`Compress::Raw::Zlib`](https://perldoc.perl.org/Compress/Raw/Zlib.html) (*core module*)
+ * [`Config::Tiny`](https://metacpan.org/pod/Config::Tiny)
+ * [`DBI`](https://metacpan.org/pod/DBI)
+ * [`DBD::SQLite`](https://metacpan.org/pod/DBD::SQLite)
+ * [`Errno`](https://perldoc.perl.org/Errno.html) (*core module*)
+ * [`Getopt::Long`](https://perldoc.perl.org/Getopt/Long.html) (*core module*)
+ * [`MIME::Base64`](https://perldoc.perl.org/MIME/Base64.html) (*core module*) — if authentication is required
+ * [`List::Util`](https://perldoc.perl.org/List/Util.html) (*core module*)
+ * [`Net::SSLeay`](https://metacpan.org/pod/Net::SSLeay) ≥1.73
+ * [`POSIX`](https://perldoc.perl.org/POSIX.html) (*core module*)
+ * [`Socket`](https://perldoc.perl.org/Socket.html) (*core module*)
+ * [`Time::HiRes`](https://perldoc.perl.org/Time/HiRes.html) (*core module*) — if `logfile` is set
+
+On Debian GNU/Linux systems, the dependencies can be installed with the
+following command:
+
+ $ apt install libconfig-tiny-perl \
+ libdbi-perl \
+ libdbd-sqlite3-perl \
+ libnet-ssleay-perl
+
+Additional packages are required in order to run the test suite:
+
+ $ apt install dovecot-imapd procps sqlite3 xxd
+<!-- -->
+ $ make test
+
+
+Generate documentation
+======================
+
+Yet another set of packages is needed to generate the documentation:
+
+ $ apt install jq pandoc
+
+Run `` `make manual` `` (or just `` `make` ``) in order to generate the
+manpages. You'll find them at `doc/*.[1-9]`. Use for instance `` `man
+-l doc/interimap.1` `` in order to read your copy of the [`interimap`(1)]
+manpage.
+
+The HTML documentation can be built with `` `make html` ``. HTML files
+are generated alongside their Markdown source by default, but you can
+choose another target directory using the `HTML_ROOTDIR` environment
+variable (the value of which defaults to `./doc`). Moreover the
+[`libjs-bootstrap`](https://tracker.debian.org/libjs-bootstrap) is
+needed by default for the local CSS file; this can be controlled with
+the `CSS` environment variable (the value of which defaults to
+`/usr/share/javascript/bootstrap/css/bootstrap.min.css`).
+
+For instance, use
+
+ $ CSS="https://guilhem.org/static/css/bootstrap.min.css" \
+ HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \
+ make html
+
+to generate the HTML documentation under directory `$XDG_RUNTIME_DIR/interimap`
+(which needs to exist) using a remote CSS file.
+
+The `doc` target generates all documentation, manpages as well as HTML
+pages.
+
+
+Build custom Debian package
+===========================
+
+Debian GNU/Linux users can also use [`gbp`(1)] from
+[`git-buildpackage`](https://tracker.debian.org/pkg/git-buildpackage) in
+order to build their own package:
+
+ $ git checkout debian
+ $ gbp buildpackage
+
+Alternatively, for the development version:
+
+ $ git checkout debian
+ $ git merge master
+ $ gbp buildpackage --git-force-create --git-upstream-tree=BRANCH
+
+
+[`interimap`(1)]: interimap.1.html
+[`gbp`(1)]: https://manpages.debian.org/git-buildpackage/gbp.1.en.html