Building and Installing Oils
============================

Oils is a new Unix shell.  This file describes how to configure, build, and
install it from the release tarball (NOT the git repo).

This doc is aimed at end users and distro maintainers.

Quick Start
-----------

If you haven't already done so, extract the tarball:
 
    tar -x --gz < oils-for-unix-0.37.0.tar.gz
    cd oils-for-unix-0.37.0

This is the traditional way to install it:

    ./configure      # completes very quickly
    _build/oils.sh   # 30-60 seconds
    sudo ./install

You'll end up with an oils-for-unix binary and two symlinks:

    /usr/local/bin/   
      oils-for-unix
      osh -> oils-for-unix
      ysh -> oils-for-unix

This structure is similar to the busybox tool.

Smoke Test
----------

OSH behaves like a POSIX shell:

    $ osh -c 'echo hi'
    hi

The -n flag parses and prints a syntax tree for the 'configure' script:

    osh -n configure

YSH is a legacy-free shell, with structured data:

    $ ysh -c 'echo hi'
    hi

    $ ysh -c 'json write ({x: 42})'
    {
      "x": 42
    }

More Documentation
------------------

Every release has a home page with links:

- <https://oils.pub/release/0.37.0/>

System Requirements
-------------------

Oils is designed to have very few dependencies.  You need:

  - A C++11 compiler
    - with libc and libstdc++
  - A POSIX shell to invoke _build/oils.sh

Optional:

  - GNU readline library, for interactive features
    (https://cnswww.cns.cwru.edu/php/chet/readline/rltop.html)

Build deps on Debian-like distros, including Ubuntu:

    sudo apt-get install build-essential libreadline-dev

Alpine Linux:

    apk add libc-dev gcc readline-dev

Oils has been tested on several Linux distros and OS X.  It aims to run on any
POSIX system.  If it doesn't, file a bug here:

- <https://github.com/oilshell/oil/issues>

Non-root Install
----------------

You can run the binary in-place, e.g.

    $ _bin/cxx-opt-sh/osh -c 'echo hi'
    hi

Or you can install into ~/bin, with the man page at
~/.local/share/man/man1/osh.1:

    ./configure --prefix ~ --datarootdir ~/.local/share
    _build/oils.sh
    ./install

This doesn't require root access, but it requires:

- ~/bin to be in your $PATH
- Pages under ~/.local/share/man to be found by 'man'.  (See manpath or
  $MANPATH.)

NOTE: Out-of-tree builds are NOT currently supported, so you have to be in the
oils-for-unix-0.37.0 directory.

Build Options
-------------

Show options with:

    ./configure --help 
    _build/oils.sh --help
    ./install --help

    
Common flags to `configure`:

    --prefix
    --with-readline
    --without-readline
    --readline  # the location

Links
-----

- Mirror of the help text:
  <https://oils.pub/release/0.37.0/doc/help-mirror.html>
- Notes on portability:
  <https://oils.pub/release/0.37.0/doc/portability.html>
