commit - 878b30c0bc1446ba933dc4539438512766183500
commit + 93a25a0f974e659e24767a13790ea4e87aabef22
blob - 6e0e9d3e420d7ea2ce5d4f27309f6bf1e349e250
blob + e7dd3c65b2319cb19869cf53cabd44c65fea9bdd
--- install.txt
+++ install.txt
- INTRO(1) INTRO(1)
+ INSTALL(1) INSTALL(1)
NAME
- intro - introduction to Plan 9 from User Space
+ install - notes about Plan 9 from User Space installation
+ SYNOPSIS
+ cd /usr/local/plan9; ./INSTALL [ -b | -c ] [ -r path ]
+
DESCRIPTION
- Plan 9 is a distributed computing environment built at Bell
- Labs starting in the late 1980s. The system can be obtained
- from Bell Labs at http://9p.io/plan9 and runs
- on PCs and a variety of other platforms. Plan 9 became a
- convenient platform for experimenting with new ideas, appli-
- cations, and services.
+ To obtain the Plan 9 tree, use Git (see git(1)) or download
+ a tar file from https://9fans.github.io/plan9port.
- Plan 9 from User Space provides many of the ideas, applica-
- tions, and services from Plan 9 on Unix-like systems. It
- runs on FreeBSD (x86, x86-64), Linux (x86, x86-64, PowerPC
- and ARM), Mac OS X (x86, x86-64, and PowerPC), NetBSD (x86
- and PowerPC), OpenBSD (x86 and PowerPC), Dragonfly BSD
- (x86-64), and SunOS (x86-64 and Sparc).
+ The tree can be unpacked anywhere, but the usual place is
+ /usr/local/plan9. In the root of the tree, run ./INSTALL.
+ This script builds the Plan 9 build program mk(1) if neces-
+ sary, cleans all previously built object files and libraries
+ out of the tree, rebuilds and installs everything, and then
+ cleans up.
- Commands
- Plan 9 from User Space expects its own directory tree, con-
- ventionally /usr/local/plan9. When programs need to access
- files in the tree, they expect the $PLAN9 environment vari-
- able to contain the name of the root of the tree. See
- install(1) for details about installation.
+ There are a few files in tree which have the root hard-coded
+ in them. After the build, INSTALL edits these files to
+ replace the string /usr/local/plan9 with the name of the
+ root of the current tree.
- Many of the familiar Unix commands, for example cat(1),
- ls(1), and wc(1), are present, but in their Plan 9 forms:
- cat takes no options, ls does not columnate its output when
- printing to a terminal, and wc counts UTF characters. In
- some cases, the differences are quite noticeable: grep(1)
- and sed(1) expect Plan 9 regular expressions (see
- regexp(7)), which are closest to what Unix calls extended
- regular expressions. Because of these differences, it is
- not recommended to put $PLAN9/bin before the usual system
- bin directories in your search path. Instead, put it at the
- end of your path and use the 9(1) script when you want to
- invoke the Plan 9 version of a traditional Unix command.
+ Finally, INSTALL builds an HTML version of the manual and
+ installs it in /usr/local/plan9/man.
- Occasionally the Plan 9 programs have been changed to adapt
- to Unix. Mk(1) now allows mkfiles to choose their own
- shell, and rc(1) has a ulimit builtin and manages $PATH.
+ The installation can be thought of as two steps: build all
+ the binaries, and then edit files as necessary to fix the
+ references to the installation root. If necessary, these
+ can be run separately. Given the -b flag, INSTALL performs
+ only the first step. Given the -c flag, INSTALL performs
+ only the second step. The first step can be done with the
+ tree in a temporary work directory, but the second step must
+ be done once the tree is in its final location. If you want
+ to build the project in one location and then install into
+ another location, use -r path to specify the final location
+ of Plan9 tree. These flags are only necessary when trying
+ to conform to the expectations of certain package management
+ systems.
- Many of the graphical programs from Plan 9 are present,
- including sam(1) and acme(1). An X11 window manager rio(1)
- mimics Plan 9's window system, with command windows imple-
- mented by the external program 9term(1). Following the style
- of X Windows, these programs run in new windows rather than
- the one in which they are invoked. They all take a -W
- option to specify the size and placement of the new window.
- The argument is one of widthxheight, widthxheight@xmin,xmax,
+ At the end of the installation, INSTALL prints suggested
+ settings for the environment variables $PLAN9 and $PATH.
- Page 1 Plan 9 (printed 12/1/14)
+ INSTALL writes various autodetected settings to
+ /usr/local/plan9/config. The file
+ /usr/local/plan9/LOCAL.config is appended to config after
+ this auto-detection and can be used to override the choices.
+ If LOCAL.config contains a line WSYSTYPE=nowsys then the
+ system is built without using X11. LOCAL.config may also
+ list settings for CC9 (the host C compiler) and CC9FLAGS
+ (any additional flags to pass to the compiler). Values more
- INTRO(1) INTRO(1)
+ Page 1 Plan 9 (printed 4/9/21)
- or xmin,ymin,xmax,ymax.
+ INSTALL(1) INSTALL(1)
- The plumber(4) helps to connect the various Plan 9 programs
- together, and fittings like web(1) connect it to external
- programs such as web browsers; one can click on a URL in
- acme and see the page load in Firefox.
+ complex than single words should be quoted with single
+ quotes.
- User-level file servers
- In Plan 9, user-level file servers present file trees via
- the Plan 9 file protocol, 9P. Processes can mount arbitrary
- file servers and customize their own name spaces. These
- facilities are used to connect programs. Clients interact
- with file servers by reading and writing files.
+ On most Linux systems, the X11 header packages need to be
+ installed to build using X11. On Debian. the required pack-
+ ages are libfontconfig1-dev, libx11-dev, libxext-dev, and
+ libxt-dev. On Ubuntu, it suffices to install xorg-dev.
- This cannot be done directly on Unix. Instead the servers
- listen for 9P connections on Unix domain sockets; clients
- connect to these sockets and speak 9P directly using the
- 9pclient(3) library. Intro(4) tells more of the story. The
- effect is not as clean as on Plan 9, but it gets the job
- done and still provides a uniform and easy-to-understand
- mechanism. The 9p(1) client can be used in shell scripts or
- by hand to carry out simple interactions with servers.
- Netfiles(1) is an experimental client for acme.
+ INSTALL can safely be repeated to rebuild the system from
+ scratch.
- External databases
- Some programs rely on large databases that would be cumber-
- some to include in every release. Scripts are provided that
- download these databases separately. These databases can be
- downloaded separately. See $PLAN9/dict/README and
- $PLAN9/sky/README.
+ Once the system is built for the first time, it can be main-
+ tained and rebuilt using mk(1). To rebuild individual com-
+ mands or libraries, run mk install and mk clean in the
+ appropriate source directory (see src(1)).
- Programming
- The shell scripts 9c and 9l (see 9c(1)) provide a simple
- interface to the underlying system compiler and linker, sim-
- ilar to the 2c and 2l families on Plan 9. 9c compiles
- source files, and 9l links object files into executables.
- When using Plan 9 libraries, 9l infers the correct set of
- libraries from the object files, so that no -l options are
- needed.
+ FILES
+ /usr/local/plan9/lib/moveplan9.files
+ the list of files that need to have /usr/local/plan9
+ edited out of them
- The only way to write multithreaded programs is to use the
- thread(3) library. Rfork(3) exists but is not as capable as
- on Plan 9. There are many unfortunate by necessary prepro-
- cessor diversions to make Plan 9 and Unix libraries coexist.
- See intro(3) for details.
+ /usr/local/plan9/lib/moveplan9.sh
+ the script that edits the files
- The debuggers acid(1) and db(1) and the debugging library
- mach(3) are works in progress. They are platform-
- independent, so that x86 Linux core dumps can be inspected
- on PowerPC Mac OS X machines, but they are also fairly
- incomplete. The x86 target is the most mature; initial Pow-
- erPC support exists; and other targets are unimplemented.
+ /usr/local/plan9/src/mkmk.sh
+ the shell script used to build mk(1)
- Page 2 Plan 9 (printed 12/1/14)
+ /usr/local/plan9/dist/manweb
+ the shell script that builds the HTML manual
- INTRO(1) INTRO(1)
+ /usr/local/plan9/man/index.html
+ the top-level page in the HTML version of the manual
- The debuggers can only inspect, not manipulate, target pro-
- cesses. Support for operating system threads and for 64-bit
- architectures needs to be rethought. On x86 Linux systems,
- acid and db can be relied upon to produce reasonable stack
- traces (often in cases when GNU gdb cannot) and dump data
- structures, but that it is the extent to which they have
- been developed and exercised.
+ /usr/local/plan9/install.log
+ logged output from the last run of INSTALL
- Porting programs
- The vast majority of the familiar Plan 9 programs have been
- ported, including the Unicode-aware troff(1).
+ /usr/local/plan9/install.sum
+ a summary of install.log
- Of the more recent additions to Plan 9, factotum(4),
- secstore(1), and secstored(1), vac(1), vacfs(4), and
- venti(8) are all ported.
-
- A backup system providing a dump file system built atop
- Venti is in progress; see vbackup(8).
-
- Porting to new systems
- Porting the tree to new operating systems or architectures
- should be straightforward, as system-specific code has been
- kept to a minimum. The largest pieces of system-specific
- code are <u.h>, which must include the right system files
- and set up the right integer type definitions, and
- libthread, which must implement spin locks, operating system
- thread creation, and context switching routines. Portable
- implementations of these using <pthread.h> and <ucontext.h>
- already exist. If your system supports them, you may not
- need to write any system specific code at all.
-
- There are other smaller system dependencies, such as the
- terminal handling code in 9term(1) and the implementation of
- getcallerpc(3), but these are usually simple and are not on
- the critical path for getting the system up and running.
-
SEE ALSO
- The rest of this manual describes Plan 9 from User Space.
- Many of the man pages have been brought from Plan 9, but
- they have been updated, and others have been written from
- scratch.
+ intro(1), git(1)
- The manual pages are in a Unix style tree, with names like
- $PLAN9/man/man1/cat.1 instead of Plan 9's simpler
- $PLAN9/man/1/cat, so that the Unix man(1) utility can handle
- it. Some systems, for example Debian Linux, deduce the man
- page locations from the search path, so that adding
- $PLAN9/bin to your path is sufficient to cause $PLAN9/man to
- be consulted for manual pages using the system man. On other
- systems, or to look at manual pages with the same name as a
- system page, invoke the Plan 9 man directly, as in 9 man
- cat.
+ Page 2 Plan 9 (printed 4/9/21)
- Page 3 Plan 9 (printed 12/1/14)
-
- INTRO(1) INTRO(1)
-
- The manual sections follow the Unix numbering conventions,
- not the Plan 9 ones.
-
- Section (1) describes general publicly accessible commands.
-
- Section (3) describes C library functions.
-
- Section (4) describes user-level file servers.
-
- Section (7) describes file formats and protocols. (On Unix,
- section (5) is technically for file formats but seems now to
- be used for describing specific files.)
-
- Section (8) describes commands used for system administra-
- tion.
-
- Section (9p) describes the Plan 9 file protocol 9P.
-
- These pages describe parts of the system that are new or
- different from Plan 9 from Bell Labs:
-
- 9(1), 9c(1), 9p(1), 9term(1), acidtypes in acid(1),
- dial(1), git(1), label(1), the MKSHELL variable in
- mk(1), namespace(1), netfiles(1), page(1), psfonts(1),
- rio(1), web(1), wintext(1)
-
- intro(3), 9pclient(3), the unix network in dial(3),
- exits(3), get9root(3), getns(3), notify(3),
- post9pservice(3), rfork(3), searchpath(3), sendfd(3),
- udpread(3), venti(3), wait(3), wctl(3)
-
- intro(4), 9pserve(4), import(4),
-
- vbackup(8)
-
- openfd(9p)
-
- DIAGNOSTICS
- In Plan 9, a program's exit status is an arbitrary text
- string, while on Unix it is an integer. Section (1) of this
- manual describes commands as though they exit with string
- statuses. In fact, exiting with an empty status corresponds
- to exiting with status 0, and exiting with any non-empty
- string corresponds to exiting with status 1. See exits(3).
-
- Page 4 Plan 9 (printed 12/1/14)
-
blob - 4b173d1811500308b9a63fc72cd0a1c561f1b6fb
blob + 66f780c7297df0396bbd8553ec7531a4fea273ed
--- man/man1/install.1
+++ man/man1/install.1
.PP
On most Linux systems, the X11 header packages need to be installed
to build using X11. On Debian. the required packages are
-libx11-dev, libxext-dev, and libxt-dev.
+libfontconfig1-dev, libx11-dev, libxext-dev, and libxt-dev.
On Ubuntu, it suffices to install xorg-dev.
.PP
.I INSTALL
