zzkt/scel
1
0
Fork 0
Code Issues 7 Pull requests Actions Projects Activity

Update readme

Browse source
This commit is contained in:
John Andrews 2021-08-19 20:53:11 -04:00
parent 8503b2a3e2
commit fcfa17b6be
1 changed files with 51 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

90
README.md
View file

@ -6,70 +6,71 @@ SuperCollider/Emacs interface
There are 3 options for installation: There are 3 options for installation:
1. Using Emacs' and SuperCollider's own package managers (recommended) 1. Using SuperCollider Quarks (recommended)
2. From debian package `supercollider-emacs` 2. From debian package `supercollider-emacs`
3. From source 3. From source
Option #1 is the best cross-platform option, and is recommended. Whatever option Option #1 is the best cross-platform option, and is recommended. Whatever option
you choose, you should only install from a single source. you choose, make sure not to mix installation methods. In particular, do not
install the Quark if you already have the supercollider-emacs package or if you
compiled SuperCollider with the `-DSC_EL=ON` option. Otherwise you will get an
error from SuperCollider about duplicated classes.
### Install Option 1: Native Packages ### Install Option 1: SuperCollider's own package manager
The repository contains two subprojects. `/el` contains the emacs-lisp The repository contains two subprojects. `/el` contains the emacs-lisp
implementation. `/scide_scel` contains the SuperCollider code required to implementation. `/sc` contains the SuperCollider code required to
implement the Emacs interface. Emacs and SuperCollider each have their own implement the Emacs interface. SuperCollider has its own package system
package managers, so it is required to install each half separately. called Quarks, which we can use to install both halves.
#### Installing scel quark Evaluate this code in the SuperCollider GUI by pasting it and pressing
shift+enter:
The `scel` Quark is required for emacs to communicate with sclang. Evaluate this
code in the SuperCollider GUI:
``` supercollider ``` supercollider
Quarks.install("https://github.com/supercollider/scel"); Quarks.install("https://github.com/supercollider/scel");
``` ```
The scel repository will be downloaded to your local file system and the path The scel repository will be downloaded to your local file system and the path
will be added to your default `sclang_conf.yaml` file. If you want to change the will be added to your default `sclang_conf.yaml` file. (You can find its
yaml file used by your emacs sessions you can customize the location by evaluating `Platform.userConfigDir`)
`sclang-library-configuration-file` variable, but make sure that file loads
the scel quark.
#### Installing the emacs mode Next, find out where scel was installed. You will use this install-path in your
emacs config.
Using [straight.el](https://github.com/raxod502/straight.el), put the following ``` supercollider
in your init file: Quarks.folder.postln;
``` emacs-lisp // -> /Users/jxa/Library/Application Support/SuperCollider/downloaded-quarks
;; in ~/.emacs
(straight-use-package
'(sclang :type git
:host github
:repo "supercollider/scel"
:files ("el/*.el")))
```
Or download the repo directly to your user config directory
``` shell
git clone https://github.com/supercollider/scel.git ~/.emacs.d/scel
``` ```
Now in your emacs config, add the `/el` subdirectory to your load path
``` emacs-lisp ``` emacs-lisp
;; in ~/.emacs ;; in ~/.emacs
(add-to-list 'load-path "~/.emacs.d/scel/el/")
;; Paste path from above, appending "/scel/el"
(add-to-list 'load-path "/Users/jxa/Library/Application Support/SuperCollider/downloaded-quarks/scel/el")
(require 'sclang) (require 'sclang)
``` ```
#### On macOS #### On macOS
If `sclang` executable is not on your path, you may need to add it to your If `sclang` executable is not on your path, you may need to add it to your
exec-path. exec-path.
``` emacs-lisp ``` emacs-lisp
;; in ~/.emacs
(setq exec-path (append exec-path '("/Applications/SuperCollider.app/Contents/MacOS/"))) (setq exec-path (append exec-path '("/Applications/SuperCollider.app/Contents/MacOS/")))
``` ```
#### Installing with an emacs package manager
It's completely possible to install with
[straight.el](https://github.com/raxod502/straight.el),
[use-package](https://github.com/jwiegley/use-package),
[doom](https://github.com/hlissner/doom-emacs), etc. Instructions for doing so
are beyond the scope of this README, but note that `autoloads` are implemented
for entry-point functions so if you like to have a speedy start-up time you can
use the `:defer t` option.
### Install Option 2: Debian package ### Install Option 2: Debian package
There is a debian package which provides emacs integration called There is a debian package which provides emacs integration called
@ -97,6 +98,20 @@ the rest of the functionality without the w3m dependency.
(require 'w3m) (require 'w3m)
``` ```
## Usage
The main function which starts interacting with the sclang interpreter is
`sclang-start`. You can execute that anywhere with `M-x sclang-start`, or from
within a `.scd` buffer by pressing `C-c C-o`.
If you know you want to launch sclang when you start emacs you can use the `-f`
option to execute that function right away:
``` shell
# in your terminal
emacs -f sclang-start
```
## Configuration ## Configuration
To fine-tune the installation from within emacs' graphical customization To fine-tune the installation from within emacs' graphical customization
@ -104,13 +119,10 @@ interface, type:
`M-x sclang-customize` `M-x sclang-customize`
If you want to change from the default `sclang_conf.yaml` file used by your
## Usage emacs sessions you can customize the `sclang-library-configuration-file`
variable, but make sure that file loads the scel quark, or you won't be
Open a `.scd` file and press `C-c C-o` to start the interpreter. able to run sclang code.
You're now ready to edit, inspect and execute sclang code!
## Getting help ## Getting help