The Alda client is a Go program that parses input (Alda code), turns it into a data representation of a musical score, and sends instructions to an Alda player process to perform the score.
Once you're all set up to run the Alda client locally, have a look at the development guide for a high-level overview of the code base.
You'll need to have Go installed in order to build and run the client locally.
Go 1.19 or newer is required.
Use bin/run
to run both the Alda client and player locally.
Examples:
# equivalent to running `alda --help`
bin/run --help
# equivalent to running `alda doctor`
bin/run doctor
# equivalent to running `alda play -f ../examples/hello_world.alda`
# (Alda player processes are started in the background)
bin/run play -f ../examples/hello_world.alda
If you're already running an Alda player process locally (let's say on port 27278), then you can specify that port via the
-p, --port
option and the client will send messages to the player you have running, instead:bin/run play -p 27278 -f ../examples/hello_world.aldaIf you're developing this way, then you don't need to do anything special with your PATH.
The client expects to find the executable for the Alda player
(alda-player
) on your PATH. To make this easy when developing, there is a
bin/player-on-path
script at the root of this repository that will build the
player executable if necessary, and then run its arguments as a command in a
subshell where the directory containing the current build of alda-player
is
first on the PATH.
To make this even easier, the bin/run
convenience script already includes an
invocation of bin/player-on-path
, so you don't even need to remember to use
bin/player-on-path
. You can just use bin/run
and the current build of the
player will be available on your PATH automatically.
For example:
# NB: These commands are all run from inside the `client` directory.
# This doesn't work unless you have `alda-player` on your PATH:
$ go run main.go play -f ../examples/hello_world.alda
Starting player processes...
Dec 27 21:41:17 WRN cmd/root.go:159 > Failed to fill player pool. error="exec: \"alda-player\": executable file not found in $PATH"
no players available
exit status 1
# This works - a player process is spawned for you, using the current build of
# the player.
$ bin/run play -f ../examples/hello_world.alda
# ... output elided, building player ...
# ... output elided, building client ...
Starting player processes...
Playing...
# 🎵 music 🎶
# Alternatively, you can start an interactive subshell that's set up so that the
# current build of `alda-player` is on the PATH:
$ ../bin/player-on-path
# ... output elided, building player ...
# Now we're in a subshell with a modified PATH:
$ echo $PATH
/home/dave/code/alda/player/target/1.99.2-d31454955bdee26b844224b7a090d3a06d744090/non-windows:/home/dave/.local/bin:/home/dave/bin:/home/dave/.bin:/usr/local/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/games
# Now this works, because the directory with the current build of `alda-player`
# is on the PATH.
$ go run main.go play -f ../examples/hello_world.alda
Playing...
# 🎵 music 🎶
There are two ways to run the client locally:
-
Basic: run the
bin/run
script and pass it arguments as if you're runningalda
on your PATH. This takes a little bit longer sometimes, but it's more convenient most of the time and it's exactly like running a release executable. -
Go toolchain: use
go run
for faster builds (no need to fully compile the executable) and more control over build options. This is useful if you're more comfortable with the Go CLI, or if you'd prefer not to wait for a full build every time you want to run the client locally after making changes.
To run the client with no arguments, which displays usage information:
# equivalent to running `alda` or `alda --help`
bin/run
To run health checks to determine if Alda can run correctly:
# equivalent to running `alda doctor`
bin/run doctor
To play an Alda source file:
# equivalent to running `alda play -f ../examples/hello_world.alda`
bin/run play -f ../examples/hello_world.alda
There is a tiny bit of code generation going on, which means you need to run
go generate
first, or else the code won't
compile.
After running go generate
, you can use all of the usual go
commands, like
go build
and go run
.
Example usage of go run
:
# equivalent to running `alda` or `alda --help`
go run main.go
# equivalent to running `alda doctor`
go run main.go doctor
# equivalent to running `alda play -f ../examples/hello_world.alda`
go run main.go play -f ../examples/hello_world.alda
There is a comprehensive test suite that you can run with this command:
go test ./...
Copyright © 2019-2024 Dave Yarwood, et al
Distributed under the Eclipse Public License version 2.0.