1$Id: INSTALL,v 1.1.1.1 2015/12/17 21:58:47 christos Exp $ 2 3About mdocml, the portable mandoc distribution 4---------------------------------------------- 5The mandoc manpage compiler toolset is a suite of tools compiling 6mdoc(7), the roff(7) macro language of choice for BSD manual pages, 7and man(7), the predominant historical language for UNIX manuals. 8It includes a man(1) manual viewer and additional tools. 9For general information, see <http://mdocml.bsd.lv/>. 10 11In case you have questions or want to provide feedback, read 12<http://mdocml.bsd.lv/contact.html>. Consider subscribing to the 13discuss@ mailing list mentioned on that page. If you intend to 14help with the development of mandoc, consider subscribing to the 15tech@ mailing list, too. 16 17Enjoy using the mandoc toolset! 18 19Ingo Schwarze, Karlsruhe, March 2015 20 21 22Installation 23------------ 24Before manually installing mandoc on your system, please check 25whether the newest version of mandoc is already installed by default 26or available via a binary package or a ports system. A list of the 27latest bundled and ported versions of mandoc for various operating 28systems is maintained at <http://mdocml.bsd.lv/ports.html>. 29 30Regarding how packages and ports are maintained for your operating 31system, please consult your operating system documentation. 32To install mandoc manually, the following steps are needed: 33 341. If you want to build the CGI program, man.cgi(8), too, run the 35command "echo BUILD_CGI=1 > configure.local". Then run "cp 36cgi.h.examples cgi.h" and edit cgi.h as desired. 37 382. Run "./configure". 39This script attempts autoconfiguration of mandoc for your system. 40Read both its standard output and the file "Makefile.local" it 41generates. If anything looks wrong or different from what you 42wish, read the file "configure.local.example", create and edit 43a file "configure.local", and re-run "./configure" until the 44result seems right to you. 45 463. Run "make". 47Any POSIX-compatible make, in particular both BSD make and GNU make, 48should work. If the build fails, look at "configure.local.example" 49and go back to step 2. 50 514. Run "make -n install" and check whether everything will be 52installed to the intended places. Otherwise, put some *DIR or *NM* 53variables into "configure.local" and go back to step�2. 54 555. Run "sudo make install". If you intend to build a binary 56package using some kind of fake root mechanism, you may need a 57command like "make DESTDIR=... install". Read the *-install targets 58in the "Makefile" to understand how DESTDIR is used. 59 606. If you want to use the integrated man(1) and your system uses 61manpath(1), make sure it is configured correctly, in particular, 62it returns all directory trees where manual pages are installed. 63Otherwise, if your system uses man.conf(5), make sure it contains 64a "_whatdb" line for each directory tree, and the order of these 65lines meets your wishes. 66 677. If you compiled with database support, run the command "sudo 68makewhatis" to build mandoc.db(5) databases in all the directory 69trees configured in step 6. Whenever installing new manual pages, 70re-run makewhatis(8) to update the databases, or apropos(1) will 71not find the new pages. 72 738. To set up a man.cgi(8) server, read its manual page. 74 75Note that some man(7) pages may contain low-level roff(7) markup 76that mandoc does not yet understand. On some BSD systems using 77mandoc, third-party software is vetted on whether it may be formatted 78with mandoc. If not, groff(1) is pulled in as a dependency and 79used to install a pre-formatted "catpage" instead of directly as 80manual page source. 81 82 83Understanding mandoc dependencies 84--------------------------------- 85The mandoc(1), man(1), and demandoc(1) utilities have no external 86dependencies, but makewhatis(8) and apropos(1) depend on the 87following software: 88 891. The SQLite database system, see <http://sqlite.org/>. 90The recommended version of SQLite is 3.8.4.3 or newer. The mandoc 91toolset is known to work with version 3.7.5 or newer. Versions 92older than 3.8.3 may not achieve full performance due to the 93missing SQLITE_DETERMINISTIC optimization flag. Versions older 94than 3.8.0 may not show full error information if opening a database 95fails due to the missing sqlite3_errstr() API. Both are very minor 96problems, apropos(1) is fully usable with SQLite 3.7.5. Versions 97older than 3.7.5 may or may not work, they have not been tested. 98 992. The fts(3) directory traversion functions. 100If your system does not have them, the bundled compatibility version 101will be used, so you need not worry in that case. But be careful: the 102glibc version of fts(3) is known to be broken on 32bit platforms, 103see <https://sourceware.org/bugzilla/show_bug.cgi?id=15838>. 104If you run into that problem, set "HAVE_FTS=0" in configure.local. 105 1063. Marc Espie's ohash(3) library. 107If your system does not have it, the bundled compatibility version 108will be used, so you probably need not worry about it. 109 110 111Checking autoconfiguration quality 112---------------------------------- 113If you want to check whether automatic configuration works well 114on your platform, consider the following: 115 116The mandoc package intentionally does not use GNU autoconf because 117we consider that toolset a blatant example of overengineering that 118is obsolete nowadays, since all modern operating systems are now 119reasonably close to POSIX and do not need arcane shell magic any 120longer. If your system does need such magic, consider upgrading 121to reasonably modern POSIX-compliant tools rather than asking for 122autoconf-style workarounds. 123 124As far as mandoc is using any features not mandated by ANSI X3.159-1989 125("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems 126do not have, we intend to provide autoconfiguration tests and 127compat_*.c implementations. Please report any that turn out to be 128missing. Note that while we do strive to produce portable code, 129we do not slavishly restrict ourselves to POSIX-only interfaces. 130For improved security and readability, we do use well-designed, 131modern interfaces like reallocarray(3) even if they are still rather 132uncommon, of course bundling compat_*.c implementations as needed. 133 134Where mandoc is using ANSI C or POSIX features that some systems 135still lack and that compat_*.c implementations can be provided for 136without too much hassle, we will consider adding them, too, so 137please report whatever is missing on your platform. 138 139The following steps can be used to manually check the automatic 140configuration on your platform: 141 1421. Run "make distclean". 143 1442. Run "./configure" 145 1463. Read the file "config.log". It shows the compiler commands used 147to test the libraries installed on your system and the standard 148output and standard error output these commands produce. Watch out 149for unexpected failures. Those are most likely to happen if headers 150or libraries are installed in unusual places or interfaces defined 151in unusual headers. You can also look at the file "config.h" and 152check that no "#define HAVE_*" differ from your expectations. 153