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 There is a 9wm-derived window manager called rio.
154 Along with the terminal 9term, the emulation feels
159 All the graphical Plan 9 programs accept a new -W option
160 that can be used to specify window size. The syntax is
164 where spec can be WIDTHxHEIGHT, WIDTHxHEIGHT@XMIN,YMIN
165 'XMIN YMIN XMAX YMAX' or XMIN,YMIN,XMAX,YMAX.
169 The libraries pass along buttons 4 and 5, so if you have a
170 scroll mouse and have X configured to send the up/down
171 events as buttons 4 and 5, acme and 9term will scroll in
174 You will likely need to change your X config to enable this.
175 In my XF86Config-4 I have
177 Section "InputDevice"
181 Option "Emulate3Buttons" "off"
182 Option "Protocol" "ImPS/2"
183 Option "ZAxisMapping" "4 5"
184 Option "Device" "/dev/psaux"
187 You'll want to find your mouse section (which may have
188 a different Identifier -- just leave it alone) and edit that.
189 The "Buttons", "Protocol", "ZAxisMapping", and "Emulate3Buttons"
190 lines are all important.
194 If you'd like to help out, great!
196 The TODO file contains a small list.
198 If you port this code to other architectures, please share your changes
199 so others can benefit. See PORTING for some notes.
201 Please use diff -u or CVS (see below) to prepare patches.
205 You can use CVS to keep your local copy up-to-date as we make
206 changes and fix bugs. The idioms explained here are pretty much
207 all you need to know about CVS.
209 To check out from the anonymous CVS repository, use
213 cvs -d :pserver:anoncvs@cvs.pdos.lcs.mit.edu:/cvs login
214 cvs -d :pserver:anoncvs@cvs.pdos.lcs.mit.edu:/cvs checkout plan9
216 When prompted for a password, just hit enter.
218 If there is already a /usr/local/plan9 directory (from a previous
219 unpacking), remove it or move it out of the way. You need write
220 access to /usr/local in order to run the checkout, but after that
221 you'll only need write access to the plan9 subtree. I typically run
222 the initial checkout as root and then chown -R rsc plan9 so that
223 I can do things as rsc afterward.
225 From then on, when you want to update, you can do
230 If there are conflicts between changes you have made locally
231 and changes on the server, cvs will warn about them and leave
232 them clearly marked in the updated files.
234 If you change something and want to submit the change (please do!),
240 to generate the diff in a format that will be easy to apply.
241 (You can also use this to see what you've changed.)
243 cvs diff -D20040101 -u
245 shows you differences txixt your tree and the repository
246 as of January 1, 2004.
248 Running the cvs commands in /usr/local/plan9 makes them
249 apply to the whole tree. Running them in a subdirectory applies
250 only to the code rooted there in the code.
252 There's not much magical about /usr/local/plan9. If you
253 check out the tree in some other directory, it should work
258 Russ Cox <rsc@swtch.com>
