| 1 | Building and Installing Oils
|
| 2 | ============================
|
| 3 |
|
| 4 | Oils is a new Unix shell. This file describes how to configure, build, and
|
| 5 | install it from the release tarball (NOT the git repo).
|
| 6 |
|
| 7 | This doc is aimed at end users and distro maintainers.
|
| 8 |
|
| 9 | Quick Start
|
| 10 | -----------
|
| 11 |
|
| 12 | If you haven't already done so, extract the tarball:
|
| 13 |
|
| 14 | tar -x --gz < oils-for-unix-0.28.0.tar.gz
|
| 15 | cd oils-for-unix-0.28.0
|
| 16 |
|
| 17 | This is the traditional way to install it:
|
| 18 |
|
| 19 | ./configure # completes very quickly
|
| 20 | _build/oils.sh # 30-60 seconds
|
| 21 | sudo ./install
|
| 22 |
|
| 23 | You'll end up with an oils-for-unix binary and two symlinks:
|
| 24 |
|
| 25 | /usr/local/bin/
|
| 26 | oils-for-unix
|
| 27 | osh -> oils-for-unix
|
| 28 | ysh -> oils-for-unix
|
| 29 |
|
| 30 | This structure is similar to the busybox tool.
|
| 31 |
|
| 32 | Smoke Test
|
| 33 | ----------
|
| 34 |
|
| 35 | OSH behaves like a POSIX shell:
|
| 36 |
|
| 37 | $ osh -c 'echo hi'
|
| 38 | hi
|
| 39 |
|
| 40 | The -n flag parses and prints a syntax tree for the 'configure' script:
|
| 41 |
|
| 42 | osh -n configure
|
| 43 |
|
| 44 | YSH is a legacy-free shell, with structured data:
|
| 45 |
|
| 46 | $ ysh -c 'echo hi'
|
| 47 | hi
|
| 48 |
|
| 49 | $ ysh -c 'json write ({x: 42})'
|
| 50 | {
|
| 51 | "x": 42
|
| 52 | }
|
| 53 |
|
| 54 | More Documentation
|
| 55 | ------------------
|
| 56 |
|
| 57 | Every release has a home page with links:
|
| 58 |
|
| 59 | - <https://oils.pub/release/0.28.0/>
|
| 60 |
|
| 61 | System Requirements
|
| 62 | -------------------
|
| 63 |
|
| 64 | Oils is designed to have very few dependencies. You need:
|
| 65 |
|
| 66 | - A C++11 compiler
|
| 67 | - with libc and libstdc++
|
| 68 | - A POSIX shell to invoke _build/oils.sh
|
| 69 |
|
| 70 | Optional:
|
| 71 |
|
| 72 | - GNU readline library, for interactive features
|
| 73 | (https://cnswww.cns.cwru.edu/php/chet/readline/rltop.html)
|
| 74 |
|
| 75 | Build deps on Debian-like distros, including Ubuntu:
|
| 76 |
|
| 77 | sudo apt-get install build-essential libreadline-dev
|
| 78 |
|
| 79 | Alpine Linux:
|
| 80 |
|
| 81 | apk add libc-dev gcc readline-dev
|
| 82 |
|
| 83 | Oils has been tested on several Linux distros and OS X. It aims to run on any
|
| 84 | POSIX system. If it doesn't, file a bug here:
|
| 85 |
|
| 86 | - <https://github.com/oilshell/oil/issues>
|
| 87 |
|
| 88 | Non-root Install
|
| 89 | ----------------
|
| 90 |
|
| 91 | You can run the binary in-place, e.g.
|
| 92 |
|
| 93 | $ _bin/cxx-opt-sh/osh -c 'echo hi'
|
| 94 | hi
|
| 95 |
|
| 96 | Or you can install into ~/bin, with the man page at
|
| 97 | ~/.local/share/man/man1/osh.1:
|
| 98 |
|
| 99 | ./configure --prefix ~ --datarootdir ~/.local/share
|
| 100 | _build/oils.sh
|
| 101 | ./install
|
| 102 |
|
| 103 | This doesn't require root access, but it requires:
|
| 104 |
|
| 105 | - ~/bin to be in your $PATH
|
| 106 | - Pages under ~/.local/share/man to be found by 'man'. (See manpath or
|
| 107 | $MANPATH.)
|
| 108 |
|
| 109 | NOTE: Out-of-tree builds are NOT currently supported, so you have to be in the
|
| 110 | oils-for-unix-0.28.0 directory.
|
| 111 |
|
| 112 | Build Options
|
| 113 | -------------
|
| 114 |
|
| 115 | Show options with:
|
| 116 |
|
| 117 | ./configure --help
|
| 118 | _build/oils.sh --help
|
| 119 | ./install --help
|
| 120 |
|
| 121 |
|
| 122 | Common flags to `configure`:
|
| 123 |
|
| 124 | --prefix
|
| 125 | --with-readline
|
| 126 | --without-readline
|
| 127 | --readline # the location
|
| 128 |
|
| 129 | Links
|
| 130 | -----
|
| 131 |
|
| 132 | - Mirror of the help text:
|
| 133 | <https://oils.pub/release/0.28.0/doc/help-mirror.html>
|
| 134 | - Notes on portability:
|
| 135 | <https://oils.pub/release/0.28.0/doc/portability.html>
|