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