1$Id: INSTALL,v 1.24 2021/09/20 13:25:42 schwarze Exp $ 2 3About the portable mandoc distribution 4-------------------------------------- 5The mandoc manpage compiler toolset (formerly called "mdocml") 6is a suite of tools compiling mdoc(7), the roff(7) macro language 7of choice for BSD manual pages, and man(7), the predominant 8historical language for UNIX manuals. 9 10It includes a man(1) manual viewer and additional tools. 11For general information, see <http://mandoc.bsd.lv/>. 12 13In case you have questions or want to provide feedback, read 14<http://mandoc.bsd.lv/contact.html>. Consider subscribing to the 15discuss@ mailing list mentioned on that page. If you intend to 16help with the development of mandoc, consider subscribing to the 17tech@ mailing list, too. 18 19Enjoy using the mandoc toolset! 20 21Ingo Schwarze, Karlsruhe, September 2021 22 23 24Installation 25------------ 26Before manually installing mandoc on your system, please check 27whether the newest version of mandoc is already installed by default 28or available via a binary package or a ports system. A list of the 29latest bundled and ported versions of mandoc for various operating 30systems is maintained at <http://mandoc.bsd.lv/ports.html>. 31 32Regarding how packages and ports are maintained for your operating 33system, please consult your operating system documentation. 34To install mandoc manually, the following steps are needed: 35 361. If you want to build the CGI program, man.cgi(8), too, 37run the command "echo BUILD_CGI=1 >> configure.local". 38Then run "cp cgi.h.example cgi.h" and edit cgi.h as desired. 39 402. If you also want to build the catman(8) utility, run the 41command "echo BUILD_CATMAN=1 >> configure.local". Note that it 42is unlikely to be a drop-in replacement providing the same 43functionality as your system's "catman", if your operating 44system contains one. 45 463. Define MANPATH_DEFAULT in configure.local 47if /usr/share/man:/usr/X11R6/man:/usr/local/man is not appropriate 48for your operating system. 49 504. Run "./configure". 51This script attempts autoconfiguration of mandoc for your system. 52Read both its standard output and the file "Makefile.local" it 53generates. If anything looks wrong or different from what you 54wish, read the file "configure.local.example", create and edit 55a file "configure.local", and re-run "./configure" until the 56result seems right to you. 57 585. Run "make". 59Any POSIX-compatible make, in particular both BSD make and GNU make, 60should work. If the build fails, look at "configure.local.example" 61and go back to step 2. 62 636. Run "make -n install" and check whether everything will be 64installed to the intended places. Otherwise, put some *DIR or *NM* 65variables into "configure.local" and go back to step 4. 66 677. Optionally run the regression suite. 68Basically, that amounts to "make regress" to do a standard regression 69run, running all tests. For more fine-grained control, 70read "./mandoc -l regress/regress.pl.1", 71then run "cd regress && ./regress.pl" with optional arguments. 72The regression suite requires a reasonably modern Perl interpreter. 73Examples of systems that are too old to run the regression suite 74include Solaris 9, Solaris 10, and Mac OS X 10.4 Tiger. 75On Solaris 11, the suite does run, but some tests fail; 76look at the BUGS section of that manual page. 77 788. Run "sudo make install". If you intend to build a binary 79package using some kind of fake root mechanism, you may need a 80command like "make DESTDIR=... install". Read the *-install targets 81in the "Makefile" to understand how DESTDIR is used. 82 839. Run the command "sudo makewhatis" to build mandoc.db(5) databases 84in all the directory trees configured in step 3. Whenever installing 85new manual pages, re-run makewhatis(8) to update the databases, or 86apropos(1) will not find the new pages. 87 8810. To set up a man.cgi(8) server, read its manual page. 89 90Note that a very small number of man(7) pages contain low-level 91roff(7) markup that mandoc does not yet understand. On some BSD 92systems using mandoc, third-party software is vetted on whether it 93may be formatted with mandoc. If not, groff(1) is pulled in as a 94dependency and used to install pre-formatted "catpages" instead of 95manual page sources. This mechanism is used much less frequently 96than in the past. On OpenBSD, only 25 out of about 10000 ports 97still require formatting with groff(1). 98 99 100Understanding mandoc dependencies 101--------------------------------- 102The following libraries are required: 103 1041. zlib for decompressing gzipped manual pages. 105 1062. The fts(3) directory traversion functions. 107If your system does not have them, the bundled compatibility version 108will be used, so you need not worry in that case. But be careful: old 109glibc versions of fts(3) were known to be broken on 32bit platforms, 110see <https://sourceware.org/bugzilla/show_bug.cgi?id=11460>. 111That was presumably fixed in glibc-2.23. 112If you run into that problem, set "HAVE_FTS=0" in configure.local. 113 1143. Marc Espie's ohash(3) library. 115If your system does not have it, the bundled compatibility version 116will be used, so you probably need not worry about it. 117 118One of the chief design goals of the mandoc toolbox is to make 119sure that nothing related to documentation requires C++. 120Consequently, linking mandoc against any kind of C++ program 121would defeat the purpose and is not supported. 122 123 124Checking autoconfiguration quality 125---------------------------------- 126If you want to check whether automatic configuration works well 127on your platform, consider the following: 128 129The mandoc package intentionally does not use GNU autoconf because 130we consider that toolset a blatant example of overengineering that 131is obsolete nowadays, since all modern operating systems are now 132reasonably close to POSIX and do not need arcane shell magic any 133longer. If your system does need such magic, consider upgrading 134to reasonably modern POSIX-compliant tools rather than asking for 135autoconf-style workarounds. 136 137As far as mandoc is using any features not mandated by ANSI X3.159-1989 138("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems 139do not have, we intend to provide autoconfiguration tests and 140compat_*.c implementations. Please report any that turn out to be 141missing. Note that while we do strive to produce portable code, 142we do not slavishly restrict ourselves to POSIX-only interfaces. 143For improved security and readability, we do use well-designed, 144modern interfaces like reallocarray(3) even if they are still rather 145uncommon, of course bundling compat_*.c implementations as needed. 146 147Where mandoc is using ANSI C or POSIX features that some systems 148still lack and that compat_*.c implementations can be provided for 149without too much hassle, we will consider adding them, too, so 150please report whatever is missing on your platform. 151 152The following steps can be used to manually check the automatic 153configuration on your platform: 154 1551. Run "make distclean". 156 1572. Run "./configure" 158 1593. Read the file "config.log". It shows the compiler commands used 160to test the libraries installed on your system and the standard 161output and standard error output these commands produce. Watch out 162for unexpected failures. Those are most likely to happen if headers 163or libraries are installed in unusual places or interfaces defined 164in unusual headers. You can also look at the file "config.h" and 165check that no "#define HAVE_*" differ from your expectations. 166