User's manual. Section 1.

INTRO(1): introduction to clive

USAGE

        ; Importzx
    ; export GOROOT=/zx/sys/golang
    ; export PLAN9=/plan9
    ; export CPUTYPE=darwin_amd64
    ; export GOPATH=/zx/usr/$USER/gosrc
    ; export GOBIN=/zx/usr/$USER/bin/$CPUTYPE
    ; PATH=$PATH:/zx/bin/$CPUTYPE:/zx/bin/rc:$PLAN9/bin
    ; NS='/ /
        /zx zx!tcp!zxserver!zx!main
    '

DESCRIPTION

Clive is a system built out of services interconnected through channels and other network connections. Processes in clive run on other hosted operating systems, because there is no native clive kernel as of now.

The central part of the system is a file system (or rather, a set of file systems) exported through the zx protocol. The file system(s) may be mounted on UNIX-like systems through fuse, to permit alien (UNIX) commands to operate on Clive services. The Clive shell and other clive commands know how to speak zx directly to Clive servers.

The main tree is usually mounted at /zx and its dump can be found at /dump. The /once tree keeps stuff not be dumped. The tree at /x is used to request command execution via xcmd(1). The dump contains a frozen version of the main tree for each day. Directories named tmp or tmp.* or *.tmp or containing a file named NODUMP are never copied to the dump. Files with names starting with a dot character (.) are never dumped. See nspace(3) for the conventions of the name space.

File system services are split into finders and zx file trees. Most Clive servers are both finders and file trees.

A finder accepts find requests to find directory entries. A file tree accepts file operations on directory entries. Directory entries are sets of name/value pairs, where certain attributes are expected to exist.

Clive commands carry a per-process name-space where foreign (UNIX) or zx file systems may be imported. The name space maps name prefixes to ordered sets of directory entries and accepts find requests to gather directory entries of interest. The name space is initialized by inspecting the NS environment variable, which can be adjusted at will for different commands, and inherited when new processes are created.

Command I/O relies on input and output channels, carrying data as byte arrays, directory entries, file addresses, and other types in general. Each channel has a name and it is customary to use in, out, and err to represent the channels for standard input, output, and error.

Commands executed within ix(1) also have the ink output channel, used to let them output graphical interfaces and requests for ix to look for things or to execute commands.

Some commands accept a configuration file. The convention is to provide the configuration in the environment, or in a file at $home/lib, or in a dot-file at $home. For example, ql(1) looks for $ql, or the file $home/lib/ql, or the file $home/.ql.

File names given to most commands are a combination of a file (path) name and a predicate. Either (or both) may be missing from a name. The file name along with the predicate is used to select files matching the name/predicate pair. See names(3) for a description and examples of names and predicates.

Standard I/O in Clive happens through channels of arbitrary data types but these conventions hold:

  • Only []byte messages are considered actual data to be processed.
  • zx.Dir directory entries indicate to which file the following data refers to.
  • All other (unknown) messages are to be forwarded to the output when read from the input.
Most commands rely on these conventions so that, for example, a command lists files and retrieves file data from the server and following commands in a shell pipe-line operate on such data without knowing how to retrieve files from the server. For example: 

        ; gf src,- | gr  func | pf

gets regular files under the src directory and sends them to gr to select lines containing func, which sends the result to pf to print the result.

A Clive command may be given input files either through the standard input or, if the command accepts that, by supplying names in the command line. Names are a combination of a file name and a predicate. Note that more than one file can be sent either way. Clive is not UNIX.

Many commands accept a -u flag that makes them issue output for UNIX, and not for clive. That is the default in pf. By default, all commands process the standard stream of messages and so they would not work as expected if they are fed by a unix output stream or their output is sent to a unix device or command. The commands rf and pf convert a UNIX stream to a Clive stream and vice-versa. For example 

        ; seq 15 | rf | gr 1 | pf

Alien commands are relegated to using the FUSE provided services and are not aware of the Clive name spaces.

  • This section documents shell commands.
  • Section 2 documents source packages (in Go).
  • Section 3 documents conventions.

The synopsys in the commands follows the UNIX style, but uses curly brackets to indicate flags that may be repeated multiple times.

EXAMPLES

To import the main tree using the ZX file protocol: 

        ; Importzx

which does something like: 

        ; zxfuse -n 'tcp!crun.lsub.org!zx!dump' /dump&
    ; zxfuse -v 'tcp!crun.lsub.org!zx!main' /zx&
    ...

To work on your local tree, in the environment set by the commands in the synopsys: 

        ; export GOBIN=/zx/usr/$USER/bin/$CPUTYPE
    ; export GOPATH=/zx/usr/$USER/gosrc
    ; go install ....

To work in the system, in the same environment: 

        ; export GOBIN=/zx/bin/$CPUTYPE
    ; export GOPATH=/zx/sys
    ; go install ....

or 

        ; Go install ...

See intro(2) for an implementation example of a hello-world clive command.

SOURCE

  • /zx/sys/src/clive
  • /zx/bin/rc

SEE ALSO

User's manual. Section 1.