1 This is a port of some Plan 9 libraries and programs to Unix.
5 Tarballs will be posted nightly (but only when there are updates!) at
7 http://swtch.com/plan9port
9 /usr/local/plan9 is the suggested location to keep the software.
10 All the paths in the tarball begin with plan9/, so it's okay to unpack it
11 directly in /usr/local.
13 You can use CVS to obtain the very latest version and stay up-to-date.
18 First, you need to extract the tarball or check out the CVS tree
19 (see below for CVS). You should be able to install the tree anywhere
20 -- tools check the environment variable $PLAN9 for the root of the
21 tree. Most of them assume /usr/local/plan9 if $PLAN9 is not set.
23 To build and install, cd into the plan9/ directory and run "./INSTALL".
24 This will first build "mk" and then use mk to build the rest of the
25 system, installing libraries in plan9/lib/ and binaries in plan9/bin/.
26 There are a few shell scripts already included in bin -- B, E,
27 and samsave. Arguably these directories should be broken up by
30 During the initial build of mk, you will likely see a message like
33 Error: can't open getcallerpc-386.s for reading
34 getcallerpc-386.s: No error
36 This is not a problem. The script tries to build getcallerpc
37 from assembly and then C. As long as one of them succeeds, great.
39 There are various directories that are not built by default.
40 They are listed in the BUGGERED definitions in src/mkfile and src/cmd/mkfile.
41 These aren't built because they're not quite ready for prime time.
42 Either they don't actually build or they haven't been very well tested.
44 As of this writing, factotum is buggered because it's not done yet,
45 and Venti and vac are buggered because they've hardly been tested
46 and are in a state of flux (they were both quite rewritten for the port).
51 The bin/ directory contains shell scripts 9a, 9c, 9l, and 9ar that mimic
52 the Plan 9 tools pretty well, except in the object names: "9c x.c" produces
53 x.o not x.9, and "9l x.o" produces "a.out" not "9.out" or "o.out".
55 Mkfiles look substantially the same as in Plan 9, with slightly different
56 names for the included rules. The most significant
57 difference is that, since there is no autolinker, the Plan 9 libraries
58 needed must be named explicitly. The variable SHORTLIBS can
59 be used to list them without giving paths, e.g.:
61 SHORTLIBS=thread bio 9
63 The default is "SHORTLIBS=9". (Libc is known as lib9; libregexp is
64 known as libregexp9; the rest of the libraries retain their usual names.)
66 Various function names (like open, accept, dup, malloc) are #defined in
67 order to provide routines that mimic the Plan 9 interface better
68 (for example, open handles the OCEXEC flag). Lib9.h contains these
69 definitions. Function "foo" is #defined to "p9foo". These definitions
70 can cause problems in the rare case that other Unix headers are needed
71 as well. To avoid this, #define NOPLAN9DEFINES before including lib9.h,
72 and then add the p9 prefix yourself for the renamed functions you wish to use.
74 * 9P servers and "name spaces"
76 A few Plan 9 programs, notably the plumber and acme, are heavily
77 dependent on the use of 9P to interact with other programs. Rather
78 than rewrite them, they have been left alone. Via the helper program 9pserve,
79 they post a Unix domain socket with a well-known name (for example,
80 "acme" or "plumb") in the directory /tmp/ns.$USER.$DISPLAY.
81 Clients connect to that socket and interact via 9P. 9pserve takes
82 care of muxing the various clients of that socket onto a single 9P
83 conversation with the actual server, just like the kernel does on Plan 9.
85 The choice of "namespace" directory is meant to provide a different
86 name space for each X11 session a user has. The environment variable
87 $NAMESPACE overrides this. The command "namespace" prints the
88 current name space directory.
90 In order to run normal Unix commands with their input or output
91 connected to a 9P server, there is a new 9P request "openfd" whose
92 response contains a real Unix file descriptor. 9pserve handles
93 this request by sending a normal open to the real 9P server and
94 sending back one side of a pipe. Then 9pserver forks a thread to
95 ferry bytes back and forth between its end of the pipe and the 9P
96 conversation. This works reasonably well, but has the drawback
97 that reads are no longer "demand-driven" (the ferry thread issues
98 the reads and fills the pipe regardless of whether the other end
99 of the pipe is being read) and writes cannot return errors (writes
100 to the pipe by the application will always succeed even though the
101 write in the ferry thread might actually draw an interesting error).
102 This doesn't cause too many problems in practice, but is worth
105 The command "9p" interacts with a given server to read or write
106 a particular file. Run "9p" for a usage message.
110 There is a plumber. It expects to find a plumbing rule file in
111 $HOME/lib/plumbing. $PLAN9/plumb/initial.plumbing is a
114 Sam and acme interact with the plumber as they do on Plan 9.
115 (If there is no plumber, sam falls back to a named pipe
116 as it always has on Unix.) Unlike on Plan 9, there is a "web"
117 command whose purpose is to load files or URLs in a running
118 web browser. Right now, only Mozilla Firebird and Opera are
119 supported, but it should be easy to add others to the script.
120 The plumbing rules in $PLAN9/plumb/basic know to run "web"
123 Because sam and acme read from the plumber using file descriptors
124 (and therefore the openfd hack described above), if the editor exits,
125 this fact is not noted until the ferry thread tries to write the next
126 plumbing message to the pipe. At this point the ferry thread closes
127 the corresponding plumber fid, but the plumber thinks the message
128 has been sent -- the message is lost. The message did serve a purpose --
129 now the plumber knows there are no readers of the "edit" channel,
130 so when it gets the next message it will start a new editor.
131 This situation doesn't happen often, but it is worth keeping in mind.
133 Both acme and sam try to raise themselves when they get plumbing
140 Programs executed with the middle button interact with acme by the
141 "openfd" trick described above. In a plain execution (as opposed
142 to >prog or |prog), because of the delay introduced by the pipes,
143 there is no guarantee that the command output will finish being
144 displayed before the exit status notice is displayed. This can be
147 There is a "win" shell. Of course, since we're on Unix, win can't
148 tell when programs are reading from the tty, so proper input point
149 management is right out the window.
153 If you'd like to help out, great!
155 The TODO file contains a small list.
157 If you port this code to other architectures, please share your changes
158 so others can benefit. See PORTING for some notes.
160 Please use diff -u or CVS (see below) to prepare patches.
164 You can use CVS to keep your local copy up-to-date as we make
165 changes and fix bugs. The idioms explained here are pretty much
166 all you need to know about CVS.
168 To check out from the anonymous CVS repository, use
172 cvs -d :pserver:anoncvs@cvs.pdos.lcs.mit.edu:/cvs login
173 cvs -d :pserver:anoncvs@cvs.pdos.lcs.mit.edu:/cvs checkout plan9
175 When prompted for a password, just hit enter.
177 If there is already a /usr/local/plan9 directory (from a previous
178 unpacking), remove it or move it out of the way. You need write
179 access to /usr/local in order to run the checkout, but after that
180 you'll only need write access to the plan9 subtree. I typically run
181 the initial checkout as root and then chown -R rsc plan9 so that
182 I can do things as rsc afterward.
184 From then on, when you want to update, you can do
189 If there are conflicts between changes you have made locally
190 and changes on the server, cvs will warn about them and leave
191 them clearly marked in the updated files.
193 If you change something and want to submit the change (please do!),
199 to generate the diff in a format that will be easy to apply.
200 (You can also use this to see what you've changed.)
202 cvs diff -D20040101 -u
204 shows you differences txixt your tree and the repository
205 as of January 1, 2004.
207 Running the cvs commands in /usr/local/plan9 makes them
208 apply to the whole tree. Running them in a subdirectory applies
209 only to the code rooted there in the code.
211 There's not much magical about /usr/local/plan9. If you
212 check out the tree in some other directory, it should work
217 Russ Cox <rsc@swtch.com>
