| 1 | ---
|
| 2 | default_highlighter: oils-sh
|
| 3 | ---
|
| 4 |
|
| 5 | Getting Started
|
| 6 | ===============
|
| 7 |
|
| 8 | There are many ways to use Oils!
|
| 9 |
|
| 10 | - You can use it *interactively*, or you can write "shell scripts" with it.
|
| 11 | Shell is the best language for *ad hoc* automation.
|
| 12 | - You can use it in *compatible* mode with `bin/osh`, or in *legacy-free* mode
|
| 13 | with `bin/ysh`.
|
| 14 |
|
| 15 | As of 2024, [OSH][] is mature, and [YSH][YSH] is under development. See [blog
|
| 16 | posts tagged #FAQ][blog-faqs] for more detail.
|
| 17 |
|
| 18 | [OSH]: https://oils.pub/cross-ref.html?tag=OSH#OSH
|
| 19 | [YSH]: https://oils.pub/cross-ref.html?tag=YSH#YSH
|
| 20 |
|
| 21 | This doc walks you through setting up Oils, explains some concepts, and links
|
| 22 | to more documentation.
|
| 23 |
|
| 24 | <div id="toc">
|
| 25 | </div>
|
| 26 |
|
| 27 | ## Setup
|
| 28 |
|
| 29 | ### Downloading Oils
|
| 30 |
|
| 31 | The [releases page](https://oils.pub/releases.html) links to source
|
| 32 | tarballs for every release. It also links to the documentation tree, which
|
| 33 | includes this page.
|
| 34 |
|
| 35 | ### Your Configuration Dir
|
| 36 |
|
| 37 | After running the instructions in [INSTALL](INSTALL.html), run:
|
| 38 |
|
| 39 | mkdir -p ~/.config/oils # for oshrc and yshrc
|
| 40 | mkdir -p ~/.local/share/oils # for osh_history
|
| 41 |
|
| 42 | ### Initialization with `rc` Files
|
| 43 |
|
| 44 | Note that
|
| 45 |
|
| 46 | - `bin/osh` runs `~/.config/oils/oshrc`
|
| 47 | - `bin/ysh` runs `~/.config/oils/yshrc`
|
| 48 |
|
| 49 | These are the **only** files that are "sourced". Other shells [have a
|
| 50 | confusing initialization sequence involving many files][mess] ([original][]).
|
| 51 | It's very hard to tell when and if `/etc/profile`, `~/.bashrc`,
|
| 52 | `~/.bash_profile`, etc. are executed.
|
| 53 |
|
| 54 | OSH and YSH intentionally avoid this. If you want those files, simply `source`
|
| 55 | them in your `oshrc`.
|
| 56 |
|
| 57 | - Related: the [config][] reference topic.
|
| 58 |
|
| 59 | [config]: ref/chap-front-end.html#config
|
| 60 |
|
| 61 | [mess]: https://shreevatsa.wordpress.com/2008/03/30/zshbash-startup-files-loading-order-bashrc-zshrc-etc/
|
| 62 |
|
| 63 | [original]: http://www.solipsys.co.uk/new/BashInitialisationFiles.html
|
| 64 |
|
| 65 | I describe my own `oshrc` file on the Wiki: [How To Test
|
| 66 | OSH](https://github.com/ols-for-unix/oils/wiki/How-To-Test-OSH).
|
| 67 |
|
| 68 | ### Setting the Prompt
|
| 69 |
|
| 70 | OSH supports the `$PS1` variable, with bash-style escape codes. See [PS1][] for details.
|
| 71 |
|
| 72 | Example:
|
| 73 |
|
| 74 | # oshrc
|
| 75 | PS1='\s '
|
| 76 |
|
| 77 | YSH has the [renderPrompt()][renderPrompt] hook, which is a YSH function. It
|
| 78 | often uses [io.promptVal()][promptVal].
|
| 79 |
|
| 80 | Example:
|
| 81 |
|
| 82 | # yshrc
|
| 83 | func renderPrompt(io) {
|
| 84 | return (io.promptVal('s') ++ ' ')
|
| 85 | }
|
| 86 |
|
| 87 | [PS1]: ref/chap-plugin.html#PS1
|
| 88 | [renderPrompt]: ref/chap-plugin.html#renderPrompt
|
| 89 | [promptVal]: ref/chap-type-method.html#promptVal
|
| 90 |
|
| 91 | ## Getting Help
|
| 92 |
|
| 93 | Type `help` in `osh` or `ysh`, which links to URLs in the [Oils
|
| 94 | Reference](ref/index.html).
|
| 95 |
|
| 96 | ## Tips
|
| 97 |
|
| 98 | - If you get tired of typing `~/.config/oils/oshrc`, symlink it to `~/.oshrc`.
|
| 99 |
|
| 100 | ### Troubleshooting
|
| 101 |
|
| 102 | - If you're running OSH from `bash` or `zsh`, then the prompt string `$PS1` may
|
| 103 | be unintentionally inherited. Running `PS1=''` before `bin/osh` avoids this.
|
| 104 | This is also true for `$PS2`, `$PS4`, etc.
|
| 105 | - On Arch Linux and other distros,`$LANG` may not get set without
|
| 106 | `/etc/profile`. Adding `source /etc/profile` to your `oshrc` may solve this
|
| 107 | problem.
|
| 108 | - See [OSH Compatibility Tips](https://github.com/oils-for-unix/oils/wiki/OSH-Compatibility-Tips) to configure programs that rely on `eval` to initialize (e.g. starship, zoxide).
|
| 109 |
|
| 110 | ### `sh` and Bash Docs Are Useful for OSH
|
| 111 |
|
| 112 | Existing educational materials for the Unix shell apply to OSH, because they
|
| 113 | generally don't teach the quirks that OSH disallows. For example, much of the
|
| 114 | information and advice in [BashGuide][] can be used without worrying about
|
| 115 | which shell you're using. See the end of this manual for more resources.
|
| 116 |
|
| 117 | For this reason, we're focusing efforts on documenting [YSH][].
|
| 118 |
|
| 119 | ## What Is Expected to Run Under OSH
|
| 120 |
|
| 121 | "Batch" programs are most likely to run unmodified under OSH. On the other
|
| 122 | hand, Interactive programs like `.bashrc` and bash completion scripts may
|
| 123 | require small changes.
|
| 124 |
|
| 125 | - Wiki: [What Is Expected to Run Under OSH]($wiki)
|
| 126 |
|
| 127 | ## Features Unique to OSH
|
| 128 |
|
| 129 | ### Dumping the AST
|
| 130 |
|
| 131 | The `-n` flag tells OSH to parse the program rather than executing it. By
|
| 132 | default, it prints an abbreviated abstract syntax tree:
|
| 133 |
|
| 134 | $ bin/osh -n -c 'ls | wc -l'
|
| 135 | (command.Pipeline children:[(C {(ls)}) (C {(wc)} {(-l)})] negated:F)
|
| 136 |
|
| 137 | You can also ask for the full `text` format:
|
| 138 |
|
| 139 | $ bin/osh -n --ast-format text -c 'ls | wc -l'
|
| 140 | (command.Pipeline
|
| 141 | children: [
|
| 142 | (command.Simple
|
| 143 | words: [
|
| 144 | (word.Compound
|
| 145 | parts: [(word_part.Literal
|
| 146 | token:(token id:Lit_Chars val:ls span_id:0))]
|
| 147 | )
|
| 148 | ]
|
| 149 | )
|
| 150 | (command.Simple
|
| 151 | words: [
|
| 152 | (word.Compound
|
| 153 | parts: [(word_part.Literal
|
| 154 | token:(token id:Lit_Chars val:wc span_id:4))]
|
| 155 | )
|
| 156 | (word.Compound
|
| 157 | parts: [(word_part.Literal
|
| 158 | token:(token id:Lit_Chars val:-l span_id:6))]
|
| 159 | )
|
| 160 | ]
|
| 161 | )
|
| 162 | ]
|
| 163 | negated: F
|
| 164 | spids: [2]
|
| 165 | )
|
| 166 |
|
| 167 | This format is **subject to change**. It's there for debugging the parser, but
|
| 168 | sophisticated users may use it to interpret tricky shell programs without
|
| 169 | running them.
|
| 170 |
|
| 171 |
|
| 172 | ### `OILS_HIJACK_SHEBANG`
|
| 173 |
|
| 174 | This environment variable can be set to the path of a **shell**. Before OSH
|
| 175 | executes a program, it will inspect the shebang line to see if it looks like a
|
| 176 | shell script. If it does, it will use this shell instead of the one specified
|
| 177 | in the shebang line.
|
| 178 |
|
| 179 | For example, suppose you have `myscript.sh`:
|
| 180 |
|
| 181 | #!/bin/sh
|
| 182 | # myscript.sh
|
| 183 |
|
| 184 | ./otherscript.sh --flag ...
|
| 185 |
|
| 186 | and `otherscript.sh`:
|
| 187 |
|
| 188 | #!/bin/sh
|
| 189 | # otherscript.sh
|
| 190 |
|
| 191 | echo 'hello world'
|
| 192 |
|
| 193 | Then you can run `myscript.sh` like this:
|
| 194 |
|
| 195 | OILS_HIJACK_SHEBANG=osh osh myscript.sh
|
| 196 |
|
| 197 | and `otherscript.sh` will be executed with OSH rather than the `/bin/sh`.
|
| 198 |
|
| 199 | Note that `osh` appears **twice** in that command line: once for the initial
|
| 200 | run, and once for all recursive runs.
|
| 201 |
|
| 202 | (This is an environment variable rather than a flag because it needs to be
|
| 203 | **inherited**.)
|
| 204 |
|
| 205 | ### `--debug-file`
|
| 206 |
|
| 207 | Print internal debug logs to this file. It's useful to make it a FIFO:
|
| 208 |
|
| 209 | mkfifo _tmp/debug
|
| 210 | osh --debug-file _tmp/debug
|
| 211 |
|
| 212 | Then run this in another window to see logs as you type:
|
| 213 |
|
| 214 | cat _tmp/debug
|
| 215 |
|
| 216 | Related:
|
| 217 |
|
| 218 | - The `OSH_DEBUG_DIR` environment variable is the inherited version of
|
| 219 | `--debug-file`. A file named `$PID-osh.log` will be written in that
|
| 220 | directory for every shell process.
|
| 221 | - The `--xtrace-to-debug-file` flag sends `set -o xtrace` output to that file
|
| 222 | instead of to `stderr`.
|
| 223 |
|
| 224 | <!--
|
| 225 | ### Crash Dumps
|
| 226 |
|
| 227 | - TODO: `OILS_CRASH_DUMP_DIR`
|
| 228 | -->
|
| 229 |
|
| 230 | ## Appendix
|
| 231 |
|
| 232 | ### Links
|
| 233 |
|
| 234 | - [Blog Posts Tagged #FAQ][blog-faqs]
|
| 235 | tell you why OSH exists and how it's designed.
|
| 236 | - [Known Differences](known-differences.html) lists incompatibilities between
|
| 237 | OSH and other shells. They are unlikely to appear in real programs, or
|
| 238 | there is a trivial workaround.
|
| 239 |
|
| 240 | [blog-faqs]: https://www.oilshell.org/blog/tags.html?tag=FAQ#FAQ
|
| 241 |
|
| 242 | External:
|
| 243 |
|
| 244 | - [GNU Bash Manual](https://www.gnu.org/software/bash/manual/). I frequently
|
| 245 | referred to this document when implementing OSH.
|
| 246 | - [BashGuide][]. A wiki with detailed information about bash.
|
| 247 | - [BashPitfalls](https://mywiki.wooledge.org/BashPitfalls).
|
| 248 | - [Bash Cheat Sheet](https://devhints.io/bash). A short overview.
|
| 249 |
|
| 250 | [BashGuide]: https://mywiki.wooledge.org/BashGuide
|
| 251 |
|