summaryrefslogtreecommitdiff
path: root/web/noweb/src/INSTALL
blob: a56b88aedcc0fecaf0a9eedd9e9960a7fb26ecf7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
These installation instructions are for Unix systems.
For Plan 9 systems, Russ Cox has kindly provided scripts in the contrib
directory, but for installation instructions, you are on your own.
If you use Microsoft Windows,  Jim Pettigrew has written installation
instructions for Windows 7 at http://www.jim-pettigrew.com/noweb/install/.

Crucial parts of noweb are written in both Icon and Awk.  You can use
either Icon or Awk, but Icon is better:

  - If you have Icon, use the Icon version of the noweb library; this
    code speeds up noweave by a factor of 3.  The Icon versions have
    fewer bugs and provide more filters (e.g., convert LaTeX to HTML
    in documentation chunks).  Not all of the examples will work with
    the awk library.  If you have an Icon compiler and believe it
    works, set `ICONC=iconc -f l' in the Makefile.  (Icon is freely
    available from the University of Arizona, but the compiler is no
    longer maintained.)

  - As of version 2.12, the Awk code for noweb's indexing and
    cross-reference relies on the bit-manipulation primitives found
    in GNU Awk.  If you have neither Icon nor GNU Awk, you will not
    be able to index or cross-reference literate programs.
    (This breaking change was put in to enable the Awk and Icon codes
    to generate *identical* outputs, for regression testing.)


To build noweb:

  1) First point to compilers to be used to built the tools and
     library by setting these variables in the Makefile:
       CC         the name of an ANSI C compiler
       LIBSRC	  'awk' or 'icon', depending on which library you want

     Now choose locations for the noweb files, and set the appropriate
     variables in the Makefile:
       BIN        on $PATH, will hold notangle, noweave, noroots, ...
       LIB        a directory to store markup, nt, noxref, ...
       MAN        man pages will go in $MAN/man1
       TEXINPUTS  a directory TeX will look for nwmac.tex and noweb.sty
       ELISP      a directory for noweb-mode.el, for emacs 19 and up
     All of these files are *output* files, where noweb will place
     binaries and man pages that are customized for your installation.
     Therefore you should:
       - make sure you have permission to write to these directories
       - refrain from making them point into the noweb source distribution
       - arrange for BIN to be on your $PATH and MAN to be on your $MANPATH
     If you don't use emacs, just leave ELISP set to /dev/null.

  2) If your modern awk is called something other than `nawk', run the
     `awkname' script to change all references to nawk.  For example,
     `awkname gawk'.  You need to do this even if you have chosen
     LIBSRC=icon, because there are a few scripts here and there that
     are only written in awk.  If you have an HPUX system and you're
     using the vendor-supplied awk, you have a problem---see file HPUX
     for details.

     Note: the `awkname' script relies on mktemp(1) to create
     temporary files.  If your system lacks this program, you'll need
     to substitute tempfile(1) or some other means of creating a
     temporary file.

  3) Type `make boot'.  This command updates timestamps so that noweb
     does not try to build itself using noweb.

  4) Fasten your seat belt and type `make all install'.  If you want a
     nonstandard noweave, you can use the WEAVE variable in the
     Makefile; for example, `make WEAVE=noweave.simple'.  In contrast
     with previous versions, the standard noweave should work with
     HPUX and SGI Irix.

  5) If you want to install contributed software, you need the
     `contrib' hierarchy.  Get it, set the LIB variable in the
     Makefile, and type 'make all install'.  If you just want the
     nuweb parser, try
	 (cd ../contrib/norman; make LIB=$LIB all install)
     where $LIB is the noweb LIB directory.

  6) On some installations, (e.g., Unix teTeX), you may have to run
     texhash(1) before TeX or latex will see files added to TEXINPUTS.

  7) You can clean up by typing `make clean'.  If you wish, you can
     remove the pre-built sources by typing `make clobber', but then
     you will be unable to build noweb unless you already have noweb.

Instead of editing the Makefile, you can create a shell script that
invokes make with the proper variables.  `nwmake' is an example of
such a script; I use it to install noweb at Princeton using the Icon
cross-referencer and our local C compiler.  If you make your own
script, call it something else so it won't get overwritten by the
default nwmake when you unbundle a new distribution.

If you encounter a problem building noweb, try the FAQ file.