Installation Notes for Serpent on Linux

Roger B. Dannenberg

There are two versions of serpent; two are command line programs and the others are graphical interface programs (32-bit Serpent is no longer maintained):

serpent64 -- command line version, 64-bit
wxserpent64 -- serpent with wxWidgets linked in to provide a graphical interface, 64-bit

Serpent is currently released as an SVN repository and in three zip files (the "nnn" is the corresponding SVN version number):

serpent-src-nnn.zip - Source code for any platform (Linux, Win32, macOS)
(serpent64-win-nnn.zip - Win32 executables: serpent64.exe and wxs\wxserpent64.exe)
(serpent64-mac-nnn.zip - macOS (64 bit) executable and bundle: serpent64 and wxserpent64.app)

The "src" zip file contains sources for all platforms. You have to build from sources on Linux systems.

Building From Sources

To build from sources, get the "src" zip file. You can also get the very latest sources from SourceForge using SVN (subversion, a configuration management tool). The Linux command to create a serpent directory (in the current directory) with the lastest sources is:

svn checkout svn://svn.code.sf.net/p/serpent/code/trunk serpent

or, if you are a developer and plan to commit changes back to SourceForge,
svn checkout svn+ssh://rbd@svn.code.sf.net/p/serpent/code/trunk serpent

Important: If your serpent directory contains trunk, tags, and branches, check the code above and try again. For these instructions to work, all the repository files in trunk must be copied to the local working copy named serpent. E.g. you should have serpent/README.txt, serpent/32bit, and serpent/64bit. After you install liblo, you should have serpent/../liblo.

The following instructions worked for Linux (Ubuntu 14.04 LTS, linked with wxWidgets 3.1.3

You must install CMake. Probably, you have a "normal" program to install software configured for your version of Linux, such as Synaptic.
wxWidgets For wxserpent, you will probably need to build wxWidgets from sources.
(Not recommended) In principle, you could just install libwxgtk3.0-gtk3-dev and it was reported on 11/30/22 that this works, but I have had problems before, e.g. libwxgtk3.1-dev failed, maybe because the Ubuntu libraries are missing OpenGL support.)
```
sudo apt-get install libwxgtk3.0-gtk3-dev
```
- Get the sources from wxWindows 3.1.
- You will need libgtk2.0-dev and libglw1-mesa-dev (and maybe other mesa) packages.
- To build from these sources:
  
  cd wxGTK
  this is the directory of wxWidgets sources, the full path will be the value of WX_BASE_PATH (see below). You do not have to name it wxGTK, but you do need to build in wx-build, as shown below:
  mkdir wx-build cd wx-build
  
  ../configure --prefix=/home/rbd/wxGTK/wx-build --disable-shared --with-opengl --enable-monolithic
  
  Note: replace "/home/rbd/wxGTK" with the actual location of the wxWidgets source directory.
  make
- Regardless of where you get the wxWidgets library, you will need glut.h which comes from the freeglut3-dev package, so install it with something like:
```
sudo apt-get install freeglut3-dev
```
Open Sound Control is supported by 2 version sas well as O2, which is an upwards-compatible extension. I recommend O2, but if you want the old OSC interface in Serpent, I recommend the built-in version. (One advantage is it has a way to get UDP through NAT -- but if you want that, you should ask Dannenberg to put it into O2; it's not that hard now that we have example code. But maybe even better is use O2 directly. It uses MQTT to get around NAT and has many other features.) If you really want the liblo version of OSC, you need liblo, as follows:
- (Not recommended) Download liblo at the same level as serpent, e.g. /home/rbd/liblo, /home/rbd/serpent. Notice the directory should be named liblo, not liblo-0.26 or some other name. Within liblo, you should find a file named configure along with many other files, not a directory named liblo-0.26.
- Build liblo
  cd liblo ./configure --enable-static make cp src/.libs/liblo.a liblo_s64.a
O2. The recommended O2 API requires O2, which is on github:
- Get O2 into a directory named o2 at the same level as the serpent directory using
  
  git clone https://github.com/rbdannenberg/o2.git
  
  or you can just get and unzip a zip file from https://github.com/rbdannenberg/o2 (look for the “Clone or Download” button and click on “Download ZIP”.) Check that from the parent of serpent, you see o2/src and serpent/64bit, e.g., you might have ~/serpent/64bit, ~/o2/src and ~/portmidi/pm_common, etc. If you use a zip file from github, it will probably create o2-master, so rename it to o2. If you do not see o2/src, adjust directories (and note that you can't move a cloned git repository - instead, you have to clone again to the correct location.)
- Note that O2 requires the libavahi-client-dev package to be installed.
- Use ccmake and make to make O2:
  
  cd o2 - change to the o2 directory
  
  ccmake .
  run ccmake. In the ccmake interface, set BUILD_MIDI_INTERFACE to OFF, set BUILD_TESTS to ON, set BUILD_TESTS_WITH_LIBLO to OFF, set CMAKE_BUILD_TYPE to Release, and set CMAKE_INSTALL_PREFIX to /usr/local (but we're not really going to install this library into the system).
- Type c twice to configure, and g to generate a make file.
- You should be back at the shell. Type make and you should see a couple of pages of output as the O2 library is built along with some test programs.
- If there are no errors, the O2 library is built and ready for Serpent.
PortMidi
- Download PortMidi in portmedia at the same level as serpent, e.g. /home/rbd/portmidi, /home/rbd/serpent, /home/rbd/o2.
- You need ALSA, e.g. sudo apt install libasound2-dev
- Build PortMidi static library with
  
  ccmake .
  (turn off BUILD_SHARED_LIBS). It should be sufficient to build only the Release version. If the library is named libportmidi.a, rename or copy it in the same directory (e.g., /home/rbd/portmidi) to libportmidi_static.a
- the Serpent code assumes the portmidi, o2, and serpent directories all share the same parent, e.g. your home directory
ZeroMQ. (Not recommended). ZeroMQ is a legacy option for networking, but currently, Serpent is developed and tested using O2. To compile with ZeroMQ, you can either install ZeroMQ or build from sources. To install ZeroMQ, use something like:
```
sudo apt-get install libzmq3-dev
```
(Note: under Ubuntu, there's a problem. Apparently, zmq depends on the libpgm-dev package.) To build ZeroMQ from sources:
- download the latest zeromq tar file from http://zeromq.org/intro:get-the-software,
- Unpack the .tar.gz source archive as ~/zeromq
- Configure and compile:
  cd zeromq ./configure --without-libsodium make make check
- If errors come out in the previous step, there's either a change in zeromq or your computer needs some additional software. Please resort to the zeromq website above.
- I would like a word with whoever thought it was a good idea to put the product of compilation in a hidden directory. Fix it now, and avoid confusion between static and dynamic libraries by renaming this static library:
  mkdir -p lib cp src/.libs/libzmq.a lib/libzmq_s.a
Libedit. Install the libedit-dev package (if you don't have it) using something like
```
sudo apt-get install libedit-dev
```
libraries.txt. To find all these libraries, CMake uses libraries.txt, a file you must author. (My attempts to automatically locate libraries in a cross-platform way never panned out. Directly listing your libraries is much simpler in the end.)
- Copy this file to serpent/64bit/libraries.txt.
- Edit the file, following directions in the file. This file will tell CMake where to find all the libraries you have installed. One of the CMake variables there is WX_BASE_PATH. Later, the build files expect to find an executable <WX_BASE_PATH>/wx-build/wx-config, produced by wxWidgets configure scripts, that produces compiler and linker flags needed to link with wxWidgets.
use CMake to create from serpent/CMakeLists.txt as follows:

cd serpent/64bit
run the command: ccmake .
set the build type (CMAKE_BUILD_TYPE, not CMAKE_CONFIGURATION_TYPES) to Release.
There are other options:

Leave AURA_DEF set to FALSE.
If you built your own wxWidgets library, set HAVE_WX_PACKAGE to OFF; otherwise (typically) set it to ON.
If you built your own ZeroMQ library, set HAVE_ZMQ_PACKAGE to OFF; otherwise (typically) set it to ON. (It is ignored if USE_ZMQ is OFF.)
LINE_EDITING -- use histedit library to implement line editing for serpent64. You do want this ON, and there may be some annoying command line prompting bugs if this flag is OFF.
NEED_WX_RESIZE_QUALITY should be OFF. This is for compatibility in other systems/versions.
USE_GL_CANVAS should be ON, enabling OpenGL in wxSerpent.
USE_LIBLO should probably be OFF. This enables one of two Open Sound Control libraries (if USE_OSC is ON, but O2 now provides OSC compatibility and more.
USE_MIDI should probably be ON to include functions that access PortMidi library (see "Serpent and PortMidi").
USE_NETWORK should probably be ON to include functions that access network functions (see "Network Interface and Functions").
USE_O2 should probably be ON to include functions that access O2. (see "O2").
USE_OSC should probably be OFF to exclude functions that access Open Sound Control (see "Open Sound Control"). Now, O2 provides OSC functions, so you do not need the OSC functions to send OSC messages since you can do that with O2 functions.
USE_LIBLO -- only matters if USE_OSC is checked. Not recommended unless you need to parse incoming messages with timestamps and/or bundles.
USE_PROC should probably be OFF to disable a the proc facility which includes functions that support a second real-time "process" (see "Proc Interface and Functions").
USE_SHFILE should be OFF and only applies to Win32 version.
USE_STATIC_LIBS says to use static linking. This should probably be ON so you do not have to set up library search paths.
USE_THREAD includes functions that support a second real-time thread (see "Thread Interface and Functions"), and should probably be OFF.
USE_ZMQ should probably be OFF to omit zmq support and if ON, you must have the zeromq library - use O2 instead (for the ZMQ functions that this enables in Serpent, see "ZeroMQ").
WXS_STDOUT_WINDOW should probably be OFF to disable sending stdout to a wxWidgets window. The wxWidgets window is not so useful because it is not scrollable if an error occurs and a dialog box pops up for debugger input.
WX_BASE_PATH is the path to find the wxWidgets installation. (Not recommended) If you are using wxWidgets packages, set HAVE_WX_PACKAGE to ON and leave WX_BASE_PATH to the default value unknown. (But it appears that the wxWidgets package is lacking some options assumed by wxSerpent, so it may not work.) If you have built wxWidgets (recommended), set HAVE_WX_PACKAGE to OFF, and set WX_BASE_PATH to your wxWidgets folder where you installed wxWidgets. E.g. my Value string is "/home/rbd/wxmac" (without the quotes).

configure [c] a couple of times, and
generate [g].

type make to make serpent64 and wxserpent64.
The binaries will be
- serpent/64bit/serpent64
- serpent/64bit/wxsbuild/wxserpent64.

Important: Serpent Environment

Serpent uses the environment to figure out where to search for files.

You may want to copy executables to ~/bin. Then, if you set up your search path appropriately, you can run serpent or wxserpent from any command prompt and any current directory. You may need to modify your PATH environment variable to include the path(s) for serpent and wxserpent. Since serpent is in my ~/bin directory, I add this to my ~/.profile file:

PATH=$PATH:/Users/rbd/bin
export PATH

You also need to tell serpent (and wxserpent) where to search for serpent source (.srp) files. Chances are good you will be using bash, so the command is:

export SERPENTPATH=/Users/rbd/serpent/programs:/Users/rbd/serpent/lib:/Users/rbd/serpent/wxslib

You can put these commands into .profile in your home directory so they will be automatically run when you start a shell.

Testing:

Try these commands:

cd
serpent64
> print "hello world"
hello world
> exit()

cd ~/serpent/wxs
wxserpent64 init.srp

This will run the init.srp in the current directory (wxs), which is a good simple test. Then try typing print "hello world" into the window with the Eval button and click on Eval. Try

cd ~/serpent/wxslib
wxserpent64 wxs_test.srp

for more fun. You should see a screen like this: