If anything on this page is unclear, or you can't get it to work, feel free to send feedback on Github or start a thread on oilshell.zulipchat.com (log in with Github). More: Where To Send Feedback.

Also, feel free to edit the page with tips.

It would be great to add more scripts to Shell Programs That Run Under OSH.

Related: What Is Expected to Run Under OSH

Installing

• For the C++ version (oils-for-unix), run ./configure, _build/oils.sh, sudo ./install. See INSTALL.txt in the tarball.

Notes

• osh behaves just like /bin/bash:
  • osh -c 'echo hi'
  • osh myscript.sh
  • Or source myprog.sh within OSH.
  • etc.
• The startup file is ~/.config/oils/oshrc
  • Make an ~/.oshrc symlink if that gets annoying to type.
• Our temporary fork of the bash-completion project has some required features: https://github.com/oilshell/bash-completion
  • Check out branch dev/osh-release-0.6.pre15
  • I also had to fork git-completion.bash and patch it. Example: Patch git completion to use compopt +o nospace

Feel free to add notes here

• Tips to get a script to work?

Channels for Feedback

• File issues on Github
• oilshell.zulipchat.com (log in with Github)
  • Feel free to post a message to #oil-discuss if a script you use works under OSH! It doesn't have to be a bug report :-)

Other Ways To Help

• Write failing Spec Tests! This is often more than half the work
  • e.g. spec/nix-idioms.test.sh, spec/ble-idioms.test.sh
• Improve error messages
  • Add a number like OILS-ERR-300
  • Then write hints and actions associated with the error in Oils Error Catalog, With Hints

Useful Features for Testing

(Some of these might only work in Python?)

(1) Run osh with OSH_HIJACK_SHEBANG=<shell>

Example:

OSH_HIJACK_SHEBANG=$(which osh) osh -c 'echo hi; ./myscript.sh'

# Now myscript.sh will be excuted with OSH if its shebang looks like #!/bin/sh or #!/bin/bash.

(2) Run OSH with --debug-file FIFO. The argument is a file to write log messages to. It's useful to make it a FIFO / named pipe.

In tmux, I open up a shell with --debug-file tmp/debug on the LEFT, and a shell that cats the debug stream on the RIGHT.

Example:

$ mkfifo _tmp/debug  # named pipe

$ osh --debug-file _tmp/debug    # do this on the LEFT.  
                                 # You can also set -x and PS4='+$LINENO '
                                 # Type commands here like 'source testdata/completion/git'.
$ cat _tmp/debug                 # do this on the RIGHT.

Also see Debugging Completion Scripts

My oshrc file

PS1='[osh] \h \w\$ '  # so I know I'm running OSH

oil_repo=~/git/oilshell/oil

# Load git completion plugin.
. $oil_repo/testdata/completion/git

# Load my bashrc, which I have patched.  I use the absence of $BASH_VERSION to test for OSH.
. ~/.bashrc

The .bashrc loads my own custom completions, which fall back on the temporary fork of bash-completion (URL and branch above). Example:

. ~/git/oilshell/bash-completion/osh_completion` # this script is a modified version of bash_completion