Getting Started

There are many ways to use Oil!

As of 2021, the OSH language is mature, and the Oil language is under development. The interactive shell exists, but it will be spartan until clients for the "headless shell" appear. (You should still try it!)

See blog posts tagged #FAQ for more detail.

This doc walks you through setting up Oil, explains some concepts, and links to more documentation.

Table of Contents
Setup
Downloading Oil
Your Configuration Dir
Initialization with rc Files
Tips
Troubleshooting
sh and Bash Docs Are Useful for OSH
What Is Expected to Run Under OSH
Features Unique to OSH
Dumping the AST
OSH_HIJACK_SHEBANG
--debug-file
Crash Dumps
More
Appendix
Bugs
Links

Setup

Downloading Oil

The releases page links to source tarballs for every release. It also links to the documentation tree, which includes this page.

Your Configuration Dir

After running the instructions in INSTALL, run:

mkdir -p ~/.config/oil

OSH will create osh_history there to store your command history.

Initialization with rc Files

You can also create your own startup files in this directory:

These are the only files that are "sourced". Other shells have a confusing initialization sequence involving many files (original). It's very hard to tell when and if /etc/profile, ~/.bashrc, ~/.bash_profile, etc. are executed.

OSH and Oil intentionally avoid this. If you want those files, simply source them in your oshrc.

I describe my own oshrc file on the Wiki: How To Test OSH.

Tips

Troubleshooting

sh and Bash Docs Are Useful for OSH

Existing educational materials for the Unix shell apply to OSH, because they generally don't teach the quirks that OSH disallows. For example, much of the information and advice in BashGuide can be used without worrying about which shell you're using. See the end of this manual for more resources.

For this reason, we're focusing efforts on documenting the Oil language.

What Is Expected to Run Under OSH

"Batch" programs are most likely to run unmodified under OSH. On the other hand, Interactive programs like .bashrc and bash completion scripts may require small changes.

Features Unique to OSH

Dumping the AST

The -n flag tells OSH to parse the program rather than executing it. By default, it prints an abbreviated abstract syntax tree:

$ bin/osh -n -c 'ls | wc -l'
(command.Pipeline children:[(C {(ls)}) (C {(wc)} {(-l)})] negated:F)

You can also ask for the full text format:

$ bin/osh -n --ast-format text -c 'ls | wc -l'
(command.Pipeline
  children: [
    (command.Simple
      words: [
        (word.Compound
          parts: [(word_part.Literal
                   token:(token id:Lit_Chars val:ls span_id:0))]
        )
      ]
    )
    (command.Simple
      words: [
        (word.Compound
          parts: [(word_part.Literal
                   token:(token id:Lit_Chars val:wc span_id:4))]
        )
        (word.Compound
          parts: [(word_part.Literal
                   token:(token id:Lit_Chars val:-l span_id:6))]
        )
      ]
    )
  ]
  negated: F
  spids: [2]
)

This format is subject to change. It's there for debugging the parser, but sophisticated users may use it to interpret tricky shell programs without running them.

OSH_HIJACK_SHEBANG

This environment variable can be set to the path of a shell. Before OSH executes a program, it will inspect the shebang line to see if it looks like a shell script. If it does, it will use this shell instead of the one specified in the shebang line.

For example, suppose you have myscript.sh:

#!/bin/sh
# myscript.sh

./otherscript.sh --flag ...

and otherscript.sh:

#!/bin/sh
# otherscript.sh

echo 'hello world'

Then you can run myscript.sh like this:

OSH_HIJACK_SHEBANG=osh osh myscript.sh

and otherscript.sh will be executed with OSH rather than the /bin/sh.

Note that osh appears twice in that command line: once for the initial run, and once for all recursive runs.

(This is an environment variable rather than a flag because it needs to be inherited.)

--debug-file

Print internal debug logs to this file. It's useful to make it a FIFO:

mkfifo _tmp/debug
osh --debug-file _tmp/debug

Then run this in another window to see logs as you type:

cat _tmp/debug

Related:

Crash Dumps

This is implemented, but a JSON library isn't in the release build.

More

For more features unique to Oil, see Why Use Oil?

Appendix

Bugs

Links

External:


Generated on Wed May 3 15:38:09 EDT 2023