INSTALL revision 316420
1$Id: INSTALL,v 1.17 2016/07/19 22:40:33 schwarze 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, July 2016 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. Define MANPATH_DEFAULT in configure.local 39if /usr/share/man:/usr/X11R6/man:/usr/local/man is not appropriate 40for your operating system. 41 423. Run "./configure". 43This script attempts autoconfiguration of mandoc for your system. 44Read both its standard output and the file "Makefile.local" it 45generates. If anything looks wrong or different from what you 46wish, read the file "configure.local.example", create and edit 47a file "configure.local", and re-run "./configure" until the 48result seems right to you. 49On Solaris 10 and earlier, you may have to run "ksh ./configure" 50because the native /bin/sh lacks some POSIX features. 51 524. Run "make". 53Any POSIX-compatible make, in particular both BSD make and GNU make, 54should work. If the build fails, look at "configure.local.example" 55and go back to step 2. 56 575. Run "make -n install" and check whether everything will be 58installed to the intended places. Otherwise, put some *DIR or *NM* 59variables into "configure.local" and go back to step 3. 60 616. Run "sudo make install". If you intend to build a binary 62package using some kind of fake root mechanism, you may need a 63command like "make DESTDIR=... install". Read the *-install targets 64in the "Makefile" to understand how DESTDIR is used. 65 667. Run the command "sudo 67makewhatis" to build mandoc.db(5) databases in all the directory 68trees configured in step 6. Whenever installing new manual pages, 69re-run makewhatis(8) to update the databases, or apropos(1) will 70not find the new pages. 71 728. To set up a man.cgi(8) server, read its manual page. 73 74Note that some man(7) pages may contain low-level roff(7) markup 75that mandoc does not yet understand. On some BSD systems using 76mandoc, third-party software is vetted on whether it may be formatted 77with mandoc. If not, groff(1) is pulled in as a dependency and 78used to install a pre-formatted "catpage" instead of directly as 79manual page source. 80 81 82Understanding mandoc dependencies 83--------------------------------- 84The following libraries are required: 85 861. zlib for decompressing gzipped manual pages. 87 882. The fts(3) directory traversion functions. 89If your system does not have them, the bundled compatibility version 90will be used, so you need not worry in that case. But be careful: the 91glibc version of fts(3) is known to be broken on 32bit platforms, 92see <https://sourceware.org/bugzilla/show_bug.cgi?id=15838>. 93If you run into that problem, set "HAVE_FTS=0" in configure.local. 94 953. Marc Espie's ohash(3) library. 96If your system does not have it, the bundled compatibility version 97will be used, so you probably need not worry about it. 98 99One of the chief design goals of the mandoc toolbox is to make 100sure that nothing related to documentation requires C++. 101Consequently, linking mandoc against any kind of C++ program 102would defeat the purpose and is not supported. 103 104 105Checking autoconfiguration quality 106---------------------------------- 107If you want to check whether automatic configuration works well 108on your platform, consider the following: 109 110The mandoc package intentionally does not use GNU autoconf because 111we consider that toolset a blatant example of overengineering that 112is obsolete nowadays, since all modern operating systems are now 113reasonably close to POSIX and do not need arcane shell magic any 114longer. If your system does need such magic, consider upgrading 115to reasonably modern POSIX-compliant tools rather than asking for 116autoconf-style workarounds. 117 118As far as mandoc is using any features not mandated by ANSI X3.159-1989 119("ANSI C") or IEEE Std 1003.1-2008 ("POSIX") that some modern systems 120do not have, we intend to provide autoconfiguration tests and 121compat_*.c implementations. Please report any that turn out to be 122missing. Note that while we do strive to produce portable code, 123we do not slavishly restrict ourselves to POSIX-only interfaces. 124For improved security and readability, we do use well-designed, 125modern interfaces like reallocarray(3) even if they are still rather 126uncommon, of course bundling compat_*.c implementations as needed. 127 128Where mandoc is using ANSI C or POSIX features that some systems 129still lack and that compat_*.c implementations can be provided for 130without too much hassle, we will consider adding them, too, so 131please report whatever is missing on your platform. 132 133The following steps can be used to manually check the automatic 134configuration on your platform: 135 1361. Run "make distclean". 137 1382. Run "./configure" 139 1403. Read the file "config.log". It shows the compiler commands used 141to test the libraries installed on your system and the standard 142output and standard error output these commands produce. Watch out 143for unexpected failures. Those are most likely to happen if headers 144or libraries are installed in unusual places or interfaces defined 145in unusual headers. You can also look at the file "config.h" and 146check that no "#define HAVE_*" differ from your expectations. 147