Using the terminal
An introduction to using Bela on the command line
Though it’s small, Bela is a full Linux system. As well as using the browser-based IDE, you can manipulate the files in your Bela system using your computer’s command line. On this page, we show you the basics of interacting with Bela using the command line. Open a terminal and go through the instructions below, and try some of the techniques listed here.
(Note that in this wiki we use the convention here that commands to be typed by the user are here displayed prepended by a
$, while the output of a program is displayed without the leading
Execute a program
Executing a program is as simple as typing its name and hit enter. Once your terminal is open, try typing the following
$ ls file1 file2 file3
again, according to the convention mentioned above, in this snippet you will only have to type
ls followed by enter, and the program will output a list of the files contained in the current folder. So we learned the command
ls, which lists the files in the current directory. Again, executing a program is as simple as typing its name followed by enter
Often times commands accept options that allow to modify their default behaviour. Most of the time, it is possible to obtain help on a command and info on the supported options by typing
--help after the program name. Make sure you leave a space between the program name and the
$ ls --help usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]
Now, the sample response above was not very informative. The response above was from a Mac OSX machine, it may be different (e.g.: more informative) on your machine.
A way of obtaining more exhaustive help on a program is to prepend the command name with
$ man ls
On systems that support
man, this will bring up a detailed help file which you can browse with the up and down arrow keys and you can quit by pressing
Pass options to a program
As mentioned, a program may allow (or require) additional options beside the command name. We have already seen two examples above of how to pass options to a program:
$ ls --help
passed the option
--help to the program
$ man ls
passed the option
ls to the program
As a general rule, the program name is going to be the first word of the line (apart for some special cases) and anything else that is separated from it by spaces is considered to be an option passed to the program. If you want to pass multiple options, you will again have to leave a space between them. For instance the following command
$ ls -l -h
will list the files in the folder with the
-l option (which means long format) and the
-h option (which means human-readable sizes).
Browsing the filesystem
You will often find that you have to move to a different folder than the one you are in before you are able to execute a particular program.
To know the folder you are currently in, use
pwd (print working directory):
$ pwd /Users/yourname
To move to a different directory, use
cd (change directory):
$ cd Desktop
you will have noticed that this command did not produce any output. Nothing to be worried about. When
cd succeeds, it produces no output.
$ cd Bela-master
if you get something like
bash: cd: Bela-master: No such file or directory
then it means that you probably did not download this [[archive|https://github.com/BelaPlatform/Bela/archive/master.zip]] and unzipped it on your desktop. Do that before proceeding and make sure the
cd Bela-master command succeeds before continuing.
Prepare to use the Bela scripts
Now that you know everything (you need) about the terminal and you are in the
Bela-master folder, have a look at the content of the
scripts/ folder. To do so run
$ cd scripts $ ls build_pd_heavy.sh build_project.sh connect_to_project.sh halt_board.sh hvresources ide.sh run_project.sh set_startup.sh setup_ssh.sh stop_running.sh update_board
Of the listed files,
hvresources is a folder (and depending on your shell’s settings, it may be displayed in a different color), while all the others are the Bela scripts.
The help for each of those can be reached adding the
--help option. This will give you a description of what the program does and what options it takes. Try, e.g.:
$ ./update_board --help
note that there is only one small (but crucial) difference from all the examples above: the program name is now preceded by a “
./”. This tells the shell to “look for the file in the current folder”. This is not needed for programs like
pwd which reside somewhere else on your disk drive.
Every time you use a Bela script, you need to prepend “
./” to its name, otherwise you would get something like
$ update_board bash: update_board: command not found