From eeed44617b8b2bf4c941f6de334a9006804615fb Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 23 Feb 2022 00:35:41 +0100 Subject: Don't assume Net::IMAP::InterIMAP is always in @INC. And make the installation path configurable at `make` time. Moreover, adjust the 'test' target so the site directory and interimap/pullimap path are configurable with INTERIMAP_I and INTERIMAP_PATH respectively. That way one can run `tests/run foo` to check the source, `make test` to check what's been built, and we also have the possibility to check the installed program e.g. for autopkgtests. --- doc/development.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/development.md b/doc/development.md index f4578b9..530c52b 100644 --- a/doc/development.md +++ b/doc/development.md @@ -136,7 +136,7 @@ and `remote` accounts. Run [`interimap`(1)] without `--watch` in order to create the database. - $ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf" + $ env -i PATH="$PATH" perl -T ./interimap --config="$BASEDIR/interimap.conf" Creating new schema in database file …/interimap.db database: Created mailbox INBOX […] @@ -144,7 +144,7 @@ Run [`interimap`(1)] without `--watch` in order to create the database. You can now run [`interimap`(1)] with `--watch` set, here to one second to observe synchronization steps early. - $ env -i PATH="$PATH" perl -I./lib -T ./interimap --config="$BASEDIR/interimap.conf" \ + $ env -i PATH="$PATH" perl -T ./interimap --config="$BASEDIR/interimap.conf" \ --watch=1 --debug Use instructions from the [previous section][Mail storage access] @@ -168,12 +168,12 @@ Create a [`pullimap`(1)] configuration file with as section `[foo]`. Run [`pullimap`(1)] without `--idle` in order to create the state file. - $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \ + $ env -i PATH="$PATH" perl -T ./pullimap --config="$BASEDIR/pullimap.conf" \ --no-delivery foo You can now run [`pullimap`(1)] with `--idle` set. - $ env -i PATH="$PATH" perl -I./lib -T ./pullimap --config="$BASEDIR/pullimap.conf" \ + $ env -i PATH="$PATH" perl -T ./pullimap --config="$BASEDIR/pullimap.conf" \ --no-delivery --idle --debug foo Use instructions from the [previous section][Mail storage access] -- cgit v1.2.3 From 448760457c85b80eef23b7c1ede8c735e4491b98 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 23 Feb 2022 02:38:25 +0100 Subject: Makefile: Rename 'test' target to 'check'. Per convention, cf. https://www.gnu.org/prep/standards/html_node/Standard-Targets.html . --- doc/build.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/build.md b/doc/build.md index 2e4e511..142097e 100644 --- a/doc/build.md +++ b/doc/build.md @@ -38,7 +38,7 @@ Additional packages are required in order to run the test suite: $ sudo apt install dovecot-imapd dovecot-lmtpd openssl procps sqlite3 xxd - $ make test + $ make check (The test suite also needs to bind to TCP ports 10024, 10143 and 10993 on the loopback interface.) -- cgit v1.2.3 From 28b2728a3232741ab3e4ccc8ced585d75fffddb1 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 23 Feb 2022 19:54:31 +0100 Subject: Fix/improve doc/build.md. Update instructions/documentation obsolete since a1c089b997ebf705a9023b4f0f97327e5bd2814e and 733ed91162b02cd0fa5d7d1c443c780d3d4405e9. --- doc/build.md | 36 +++++++++++++++--------------------- 1 file changed, 15 insertions(+), 21 deletions(-) (limited to 'doc') diff --git a/doc/build.md b/doc/build.md index 142097e..6c812dc 100644 --- a/doc/build.md +++ b/doc/build.md @@ -40,8 +40,8 @@ Additional packages are required in order to run the test suite: $ make check -(The test suite also needs to bind to TCP ports 10024, 10143 and 10993 -on the loopback interface.) +(Note also that the test suite needs to bind to TCP ports 10024, 10143 +and 10993 on the loopback interface.) Generate documentation ====================== @@ -51,29 +51,23 @@ Yet another set of packages is needed to generate the documentation: $ sudo 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. +manuals. You'll find them at `build/doc/*.[1-9]`. Then use for +instance `` `man -l build/doc/interimap.1` `` to read your local copy of +the [`interimap`(1)] manual. -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`). +The HTML documentation can be built with `` `make html` ``. By default +HTML files are generated at `build/doc/*.html`, and a local CSS file is +used — namely `/usr/share/javascript/bootstrap4/css/bootstrap.css`, +shipped the by [`libjs-bootstrap`](https://tracker.debian.org/libjs-bootstrap) +package. But this is configurable: use for instance -For instance, use + $ make html builddir="$XDG_RUNTIME_DIR/interimap" \ + CSS="https://cdn.jsdelivr.net/npm/bootstrap@4.6.1/dist/css/bootstrap.min.css" - $ env CSS="https://guilhem.org/static/css/bootstrap.min.css" \ - HTML_ROOTDIR="$XDG_RUNTIME_DIR/interimap" \ - make html +to generate the HTML documentation under `$XDG_RUNTIME_DIR/interimap/doc` +using a remote CSS file. -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 +The `doc` target generates all documentation, manuals as well as HTML pages. -- cgit v1.2.3 From 4d36557a007f06196affe14afd1a2bd2a4945c44 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Wed, 23 Feb 2022 20:00:28 +0100 Subject: Document how to install without root privileges. And make location for systemd user unit files configurable with systemd_userunitdir=. --- doc/build.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'doc') diff --git a/doc/build.md b/doc/build.md index 6c812dc..1936c13 100644 --- a/doc/build.md +++ b/doc/build.md @@ -71,6 +71,33 @@ The `doc` target generates all documentation, manuals as well as HTML pages. +Installation without root privileges +==================================== + +By default `` `make install` `` installs [`interimap`(1)] under +`/usr/local`, hence requires root privileges. However another prefix +can be used in order to perform the (un)installation as an unprivileged +user. For instance + + $ install -m0700 -vd "${XDG_DATA_HOME:-~/.local/share}/interimap" + $ make install-nodoc \ + prefix=~/.local \ + sitelib="${XDG_DATA_HOME:-~/.local/share}/interimap/lib" \ + systemd_userunitdir="${XDG_DATA_HOME:-~/.local/share}/systemd/user" + +skips documentation and installs + + * executables into `~/.local/bin` (instead of `/usr/local/bin`); + * libraries into `$XDG_DATA_HOME/interimap/lib` or `~/.local/share/interimap/lib` + (instead of `/usr/local/lib/site_perl`); and + * [systemd user unit files][`systemd.unit`(5)] into `$XDG_DATA_HOME/systemd/user` + or `~/.local/share/systemd/user` (instead of `/usr/local/lib/systemd/user`). + +Note that for uninstallation one must call `` `make uninstall prefix=…` `` +with the very same assignment(s) used for installation. + +[`systemd.unit`(5)]: https://www.freedesktop.org/software/systemd/man/systemd.unit.html + Build custom Debian packages ============================ -- cgit v1.2.3 From 404505bdf9a152ed9e0911027500b58d2c7ce72c Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Thu, 24 Feb 2022 20:15:58 +0100 Subject: Documentation: Update URL targets from https://wiki.dovecot.org to https://doc.dovecot.org . --- doc/benchmark.md | 4 ++-- doc/development.md | 4 ++-- doc/getting-started.md | 5 +++-- 3 files changed, 7 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/benchmark.md b/doc/benchmark.md index 72f51a4..f2f6cda 100644 --- a/doc/benchmark.md +++ b/doc/benchmark.md @@ -48,8 +48,8 @@ by placing packet counters on the interface. [OfflineIMAP]: https://www.offlineimap.org/ [benchmark-script]: https://git.guilhem.org/interimap/plain/benchmark/run [Dovecot]: https://dovecot.org -[dbox]: https://wiki.dovecot.org/MailboxFormat/dbox -[maildir]: https://wiki.dovecot.org/MailboxFormat/Maildir +[dbox]: https://doc.dovecot.org/admin_manual/mailbox_formats/dbox/ +[maildir]: https://doc.dovecot.org/admin_manual/mailbox_formats/maildir/ ----------------------------------------------------------------------- diff --git a/doc/development.md b/doc/development.md index 530c52b..0fe54f4 100644 --- a/doc/development.md +++ b/doc/development.md @@ -194,10 +194,10 @@ recursively remove the directory `$BASEDIR`. [IMAP4rev1]: https://tools.ietf.org/html/rfc3501 [Dovecot]: https://dovecot.org [Dovecot Logging]: https://doc.dovecot.org/admin_manual/logging/ -[Dovecot LDA]: https://wiki.dovecot.org/LDA +[Dovecot LDA]: https://doc.dovecot.org/configuration_manual/protocols/lda/ [`getlogin`(3)]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getlogin.html [User Databases]: https://doc.dovecot.org/configuration_manual/authentication/user_databases_userdb/ -[Maildir]: https://wiki.dovecot.org/MailLocation/Maildir +[Maildir]: https://doc.dovecot.org/configuration_manual/mail_location/Maildir/ [RFC 2342]: https://tools.ietf.org/html/rfc2342 [Dovecot Namespaces]: https://doc.dovecot.org/configuration_manual/namespace/ [`interimap`(1)]: interimap.1.html diff --git a/doc/getting-started.md b/doc/getting-started.md index 74fc8da..7a77a6b 100644 --- a/doc/getting-started.md +++ b/doc/getting-started.md @@ -84,7 +84,7 @@ mailbox delivery) then don't disable them, and modify Dovecot's system wide configuration instead. Same thing if your mail client isn't able to spawn a command for IMAP communication, and instead insists on connecting to a network socket (in that case you'll even need to -configure [user authentication](https://wiki.dovecot.org/Authentication) +configure [user authentication](https://doc.dovecot.org/configuration_manual/authentication/) for the IMAP service, which is out of scope for the present document). Run the following command to terminate and disable the system-wide @@ -113,7 +113,8 @@ Some remarks on the above: running `` `doveconf -nc ${XDG_CONFIG_HOME:-~/.config}/dovecot/dovecot.conf` ``. * Messages will be stored in Maildir format under `~/Mail`. Ensure the directory is either *empty* or *doesn't exist* before - continuing! You may want to choose a different [format](https://wiki.dovecot.org/MailboxFormat) + continuing! You may want to choose a different + [format](https://doc.dovecot.org/admin_manual/mailbox_formats/) here, or simply append `:LAYOUT=fs` to the `mail_location` value in order to use a nicer (File System like) Maildir layout. * The `separator` setting defines the IMAP hierarchy delimiter. This -- cgit v1.2.3 From 0df603bfca85e859bdf21ffe1b32ce897caf8b7d Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sun, 27 Feb 2022 16:20:43 +0100 Subject: Documentation: Replace `foo=~/bar` with `foo=$HOME/bar`. POSIX doesn't mandate expansion of the former. --- doc/build.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'doc') diff --git a/doc/build.md b/doc/build.md index 1936c13..b40760e 100644 --- a/doc/build.md +++ b/doc/build.md @@ -79,11 +79,11 @@ By default `` `make install` `` installs [`interimap`(1)] under can be used in order to perform the (un)installation as an unprivileged user. For instance - $ install -m0700 -vd "${XDG_DATA_HOME:-~/.local/share}/interimap" + $ install -m0700 -vd ${XDG_DATA_HOME:-~/.local/share}/interimap $ make install-nodoc \ - prefix=~/.local \ - sitelib="${XDG_DATA_HOME:-~/.local/share}/interimap/lib" \ - systemd_userunitdir="${XDG_DATA_HOME:-~/.local/share}/systemd/user" + prefix=$HOME/.local \ + sitelib=${XDG_DATA_HOME:-~/.local/share}/interimap/lib \ + systemd_userunitdir=${XDG_DATA_HOME:-~/.local/share}/systemd/user skips documentation and installs -- cgit v1.2.3