1 .TH INSTALL 1
2 .SH NAME
3 install \- notes about Plan 9 from User Space installation
4 .SH SYNOPSIS
5 .B
6 cd \*9; ./INSTALL
7 [
8 .B -b
9 |
10 .B -c
11 ]
12 .SH DESCRIPTION
13 To obtain the Plan 9 tree, use CVS
14 (see
15 .IR cvs (1))
16 or download a tar file from
17 .HR http://swtch.com/plan9port "" .
18 .PP
19 The tree can be unpacked anywhere, but the
20 usual place is
21 .BR /usr/local/plan9 .
22 In the root of the tree, run
23 .BR ./INSTALL .
24 This script builds the Plan 9 build program
25 .IR mk (1)
26 if necessary,
27 cleans all previously built object files and libraries out of the tree,
28 rebuilds and installs everything, and then cleans up.
29 .PP
30 There are a few files in tree which have the root
31 hard-coded in them.
32 After the build, 
33 .I INSTALL
34 edits these files to replace the string
35 .B /usr/local/plan9
36 with the name of the root of the current tree.
37 .PP
38 Finally,
39 .I INSTALL
40 builds an HTML version of the manual and installs it in
41 .BR \*9/man .
42 .PP
43 The installation can be thought of as two steps:
44 build all the binaries, and then edit files as necessary
45 to fix the references to the installation root.
46 If necessary, these can be run separately.
47 Given the
48 .B -b
49 flag,
50 .I INSTALL
51 performs only the first step.
52 Given the
53 .B -c
54 flag,
55 .I INSTALL
56 performs only the second step.
57 The first step can be done with the tree in a temporary work directory,
58 but the second step must be done once the tree is in its final location.
59 These flags are only necessary when trying to conform to the
60 expectations of certain package management systems.
61 .PP
62 At the end of the installation,
63 .I INSTALL
64 prints suggested settings for the environment variables 
65 .B $PLAN9
66 and
67 .BR $PATH .
68 .PP
69 Plan 9 from User Space uses different threading implementations on Linux 2.6 and
70 later kernels than on 2.4 and earlier;
71 and on FreeBSD 5 and later kernels than on FreeBSD 4 and earlier.
72 Running binaries from one class on another will not work.
73 .PP
74 Some Linux 2.6 systems (e.g., Gentoo) do not use the new NPTL pthread library
75 even though the kernel supports them.  On these systems, plan9port must 
76 fall back on the threading code intended for Linux 2.4.  To accomplish this,
77 .I INSTALL
78 checks whether the running system uses NPTL and sets
79 .B SYSVERSION
80 in
81 .B \*9/config
82 accordingly.
83 The file
84 .B \*9/LOCAL.config
85 is appended to
86 .B config
87 after this auto-detection and can be used to override the choices.
88 If 
89 .B LOCAL.config
90 contains a line
91 .B WSYSTYPE=nowsys
92 then the system is built without using X11.
93 .PP
94 .I INSTALL
95 can safely be repeated to rebuild the system from scratch.
96 .PP
97 Once the system is built for the first time,
98 it can be maintained and rebuilt using 
99 .IR mk (1).
100 To rebuild individual commands or libraries,
101 run
102 .B mk
103 .B install
104 and
105 .B mk
106 .B clean
107 in the appropriate source directory
108 (see
109 .IR src (1)).
110 .SH FILES
111 .TP
112 .B \*9/lib/moveplan9.files
113 the list of files that need to have
114 .B /usr/local/plan9
115 edited out of them
116 .TP
117 .B \*9/lib/moveplan9.sh
118 the script that edits the files
119 .TP
120 .B \*9/src/mkmk.sh
121 the shell script used to build
122 .IR mk (1)
123 .TP
124 .B \*9/dist/manweb
125 the shell script that builds the HTML manual
126 .TP
127 .B \*9/man/index.html
128 the top-level page in the HTML version of the manual
129 .TP
130 .B \*9/install.log
131 logged output from the last run of
132 .I INSTALL
133 .TP
134 .B \*9/install.isum
135 a summary of
136 .B install.log
137 .SH SEE ALSO
138 .IR intro (1),
139 .IR cvs (1)