INSTALL.txt

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

Oils is a new Unix shell.  This file describes how to configure, build, and
install it from source code.

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

If you haven't already done so, extract the tarball:
 
    tar -x --gz < oils-for-unix-0.26.0.tar.gz
    cd oils-for-unix-0.26.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.26.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.26.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 the help text:
  <https://oils.pub/release/0.26.0/doc/help-mirror.html>
- Notes on portability:
  <https://oils.pub/release/0.26.0/doc/portability.html>