src.elv.sh@v0.21.0-dev.0.20240515223629-06979efb9a2a/README.md (about) 1 # Elvish: Expressive Programming Language + Versatile Interactive Shell 2 3 [](https://github.com/elves/elvish/actions?query=workflow%3ACI) 4 [](https://cirrus-ci.com/github/elves/elvish/master) 5 [](https://app.codecov.io/gh/elves/elvish/tree/master) 6 [](https://pkg.go.dev/src.elv.sh@master) 7 [](https://repology.org/project/elvish/versions) 8 [](https://twitter.com/ElvishShell) 9 10 Elvish is a powerful scripting language and a versatile interactive shell. It 11 runs on Linux, macOS, BSDs and Windows. 12 13 Elvish is pre-1.0. This means that the features set will change between 14 versions, but it's quite stable for both scripting and interactive use. 15 16 User groups (all connected thanks to [Matrix](https://matrix.org)): 17 18 [](https://t.me/+Pv5ZYgTXD-YaKwcP) 19 [](https://discord.gg/jrmuzRBU8D) 20 [](https://matrix.to/#/#users:elv.sh) 21 [](https://web.libera.chat/#elvish) 22 [](https://gitter.im/elves/elvish) 23 24 ## Documentation 25 26 Documentation for Elvish lives on the official website https://elv.sh, 27 including: 28 29 - [Learning material](https://elv.sh/learn) 30 31 - [Reference docs](https://elv.sh/ref), including the 32 [language reference](https://elv.sh/ref/language.html), 33 [the `elvish` command](https://elv.sh/ref/command.html), and all the modules 34 in the standard library 35 36 - [Blog posts](https://elv.sh/blog), including release notes 37 38 The source for the documentation is in the 39 [website](https://github.com/elves/elvish/tree/master/website) directory. 40 41 ## License 42 43 All source files use the BSD 2-clause license (see [LICENSE](LICENSE)), except 44 for the following: 45 46 - Files in [pkg/diff](pkg/diff) and [pkg/rpc](pkg/rpc) are released under the 47 BSD 3-clause license, since they are derived from 48 [Go's source code](https://github.com/golang/go). See 49 [pkg/diff/LICENSE](pkg/diff/LICENSE) and [pkg/rpc/LICENSE](pkg/rpc/LICENSE). 50 51 - Files in [pkg/persistent](pkg/persistent) and its subdirectories are 52 released under EPL 1.0, since they are partially derived from 53 [Clojure's source code](https://github.com/clojure/clojure). See 54 [pkg/persistent/LICENSE](pkg/persistent/LICENSE). 55 56 - Files in [pkg/md/spec](pkg/md/spec) are released under the Creative Commons 57 CC-BY-SA 4.0 license, since they are derived from 58 [the CommonMark spec](https://github.com/commonmark/commonmark-spec). See 59 [pkg/md/spec/LICENSE](pkg/md/spec/LICENSE). 60 61 ## Building Elvish 62 63 Most users do not need to build Elvish from source. Prebuilt binaries for the 64 latest commit are provided for 65 [Linux amd64](https://dl.elv.sh/linux-amd64/elvish-HEAD.tar.gz), 66 [macOS amd64](https://dl.elv.sh/darwin-amd64/elvish-HEAD.tar.gz), 67 [macOS arm64](https://dl.elv.sh/darwin-arm64/elvish-HEAD.tar.gz), 68 [Windows amd64](https://dl.elv.sh/windows-amd64/elvish-HEAD.zip) and 69 [many other platforms](https://elv.sh/get). 70 71 To build Elvish from source, you need 72 73 - A supported OS: Linux, {Free,Net,Open}BSD, macOS, or Windows 10. Windows 10 74 support is experimental. 75 76 - Go >= 1.21.0. 77 78 To build Elvish from source, run one of the following commands: 79 80 ```sh 81 go install src.elv.sh/cmd/elvish@master # Install latest commit 82 go install src.elv.sh/cmd/elvish@latest # Install latest released version 83 go install src.elv.sh/cmd/elvish@v0.18.0 # Install a specific version 84 ``` 85 86 ### Controlling the installation location 87 88 The 89 [`go install`](https://pkg.go.dev/cmd/go#hdr-Compile_and_install_packages_and_dependencies) 90 command installs Elvish to `$GOBIN`; the binary name is `elvish`. You can 91 control the installation location by overriding `$GOBIN`, for example by 92 prepending `env GOBIN=...` to the `go install` command. 93 94 If `$GOBIN` is not set, the installation location defaults to `$GOPATH/bin`, 95 which in turn defaults to `~/go/bin` if `$GOPATH` is also not set. 96 97 The installation directory is probably not in your OS's default `$PATH`. You 98 should either either add it to `$PATH`, or manually copy the Elvish binary to a 99 directory already in `$PATH`. 100 101 ### Building a variant 102 103 Elvish has several *build variants* with slightly different feature sets. For 104 example, the `withpprof` build variant has 105 [profiling support](https://pkg.go.dev/runtime/pprof). 106 107 These build variants are just alternative main packages. For example, to build 108 the `withpprof` variant, run the following command (change the part after `@` to 109 get different versions): 110 111 ```sh 112 go install src.elv.sh/cmd/withpprof/elvish@master 113 ``` 114 115 ### Building from a local source tree 116 117 If you are modifying Elvish's source code, you will want to clone Elvish's Git 118 repository and build Elvish from the local source tree instead. To do this, run 119 the following from the root of the source tree: 120 121 ```sh 122 go install ./cmd/elvish 123 ``` 124 125 There is no need to specify a version like `@master`; when inside a source tree, 126 `go install` will always use the whatever source code is present. 127 128 See [CONTRIBUTING.md](CONTRIBUTING.md) for more notes for contributors. 129 130 ### Building with experimental plugin support 131 132 Elvish has experimental support for building and importing plugins, modules 133 written in Go. It relies on Go's [plugin support](https://pkg.go.dev/plugin), 134 which is only available on a few platforms. 135 136 Plugin support requires building Elvish with [cgo](https://pkg.go.dev/cmd/cgo). 137 The official [prebuilt binaries](https://elv.sh/get) are built without cgo for 138 compatibility and reproducibility, but by default the Go toolchain builds with 139 cgo enabled. 140 141 If you have built Elvish from source on a platform with plugin support, your 142 Elvish build probably already supports plugins. To force cgo to be used when 143 building Elvish, you can do the following: 144 145 ```sh 146 env CGO_ENABLED=1 go install ./cmd/elvish 147 ``` 148 149 To build a plugin, see this [example](https://github.com/elves/sample-plugin). 150 151 ## Packaging Elvish 152 153 See [PACKAGING.md](PACKAGING.md) for notes for packagers. 154 155 ## Contributing to Elvish 156 157 See [CONTRIBUTING.md](CONTRIBUTING.md) for notes for contributors. 158 159 ## Reporting security issues 160 161 See [SECURITY.md](SECURITY.md) for how to report security issues.