Installation Notes for Serpent on Mac OS X

Roger B. Dannenberg

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

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

Notes on compiling for arm64 or x86_64.

Installing Compiled Programs

The executable and application bundle are serpent64 and wxserpent64.app.

Instructions:

1. When you unzip the download, you will have a directory named serpent. Put this directory in your home directory. If it is on the desktop, move it to your home directory. (If you really want it on your desktop, that is OK, but you will have to adjust these instructions accordingly.)
   
2. Your system must be able to find the executables. Move the executables to a personal directory of executables named ~/bin. The following commands can be used:

   mkdir ~/bin
   cd ~/serpent
   mv serpent64 wxserpent64.app ~/bin

3. You also need a short script to execute wxserpent64 from within the application bundle, so create the file ~/bin/wxserpent64 with the following content; be sure to use your userid rather than "rbd":
   

   Important: If you do not know how to create or edit a text file, try running the command nano in the terminal. You should also read and learn about files, directories, paths, learn how to interpret the path ~/serpent, know what is a “hidden” file and how to list them, and more options for text editor applications.

   #!/bin/sh
   echo "running wxserpent64 with arguments $*"
   /Users/rbd/bin/wxserpent64.app/Contents/MacOS/wxserpent64 $*

4. Make ~/bin/wxserpent64 executable as follows:

   chmod +x ~/bin/wxserpent64

5. You then need to modify something so that your shell will search in your ~/bin directory for executable programs. First, we need to find the right something to modify, and it depends on your shell. Apple changed their default shell from bash to zsh, except that Xcode still uses bash. This would be a good time to figure out which shell you are using. In a terminal, the title bar should say -zsh or -bash. Alternatively, type echo $SHELL, press RETURN, and you should see either /bin/zsh or /bin/bash.

   If you use zsh, edit .zshenv, a hidden file in your home directory. If you use bash, edit your ~/.bash_profile. (If you don’t have ~/.bash_profile, and you do have ~/.profile, use that instead.)

   Now that you know which file to edit, be sure you have a backup, since it might contain important configuration information for many programs. Open the the file in your editor and set your PATH and SERPENTPATH variables by appending the following lines (be sure to use your userid rather than "rbd"):
   

   echo "Loading ~/.zshenv"
   export PATH=$PATH:/Users/rbd/bin
   export SERPENTPATH="/Users/rbd/serpent/lib:/Users/rbd/serpent/programs:/Users/rbd/serpent/wxslib"

   (Of course, if you are editing ~/.bash_profile, type "Loading ~/.bash_profile" etc.)
6. Close and reopen the terminal window to start a new shell. To check your work, the command echo $SERPENTPATH should print the value of SERPENTPATH that you entered. echo $PATH should print a long string including /Users/<name>/bin. If these variables are not set properly, start by confirming that a new shell is loading the file you edited. Your new terminal window should say “Loading ~/.zshenv”
   

Testing: Try these commands:

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

wxserpent64 wxs_test.srp

Diagnosing Problems

Building From Sources

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

• You must have Xcode, which is available free at the Apple App Store.
  
• You must also have installed "command line tools" from https://developer.apple.com/xcode/
• You must install CMake. For OS X, this will be an ordinary application you run by double-clicking on the CMake icon in the Applications folder.
  
• Important: all libraries and applications must be built with the same SDK version, e.g. even though I'm using MacOSX13.0.sdk, I am using the MacOS 10.14 SDK for backward compatibility by setting the CMake variable CMAKE_OSX_DEPLOYMENT_TARGET to "10.14". This should be consistent across all libraries you build (wxWidgets, O2, PortMidi, etc.).
• Serpent now has 2 versions of Open Sound Control and 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.) If you really want the liblo version of OSC, you need liblo, as follows:
• Download liblo at the same level as serpent, e.g. /home/rbd/liblo, /home/rbd/serpent. Notice the directory is 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. (Notice that we are getting these sources from a downloaded tar file, not via svn.)
• zeromq is no longer standard in Serpent. See zeromq in for instructions on building with zeromq. It should work if you can compile it and libsodium with clang and libc++.
• install PortMidi in portmedia at the same level as serpent, e.g. /home/rbd/portmedia/portmidi, /home/rbd/serpent, /home/rbd/liblo.
  Details on portmidi installation for the Macintosh are here.
• build PortMidi (see documentation in Installing PortMidi on the Mac). 
• Be sure to get and install PmDefaults as well.
  
• build liblo if you want to use it

  cd liblo
  arch_flags="-arch x86_64"
  ./configure CFLAGS="$arch_flags" CXXFLAGS="$arch_flags" CPPFLAGS="$arch_flags" LDFLAGS="$arch_flags" OBJCFLAGS="$arch_flags" OBJCXXFLAGS="$arch_flags" --enable-static
  make
  mkdir Release
  cp src/.libs/liblo.a Release/liblo_s64.a
  

• the Serpent code assumes the portmedia, liblo, and serpent directories all share the same parent, e.g. your home directory
• download wxWindows 3.2.1.
• Ignore the installation directions that come with wxWindow 3.2, and use this instead (Be sure to change /Users/rbd/ to the correct prefix in the configure command):

cd wxWidgets-3.2.1 <- this is the directory of wxWindows sources,
                   <- the full path will be the value of
                   <- WX_BASE_PATH (see below) this example
                   <- is obviously for wxWidgets-3.2.1, but
                   <- use the actual directory name for your
                   <- wxWidgets sources if it differs.
mkdir wx-build

cd wx-build
../configure --with-osx-cocoa --with-macosx-version-min=10.10 --prefix=/Users/rbd/wxWidgets-3.2.1/wx-build --with-opengl --enable-monolithic --disable-shared --with-libtiff=builtin --with-libpng=builtin --with-libjpeg=builtin


make

Note 1: you might want to omit the with-macosx-version-min and with-macosx-sdk parameters. I used them to try to build Serpent to be compatible with earlier macOS systems, but Apple is really aggressive about expunging older versions and backward compatibility. More recent XCode installations will not be capable of this backward compatibility.

Note 2: options --with-libpng=builtin --with-libjpeg=builtin were added Jun 2024 because it solved one system’s failure to link when the options were omitted (the default is --with-libpng=sys --with-libjpeg=sys which means the libraries are expected to be installed already.

• use CMake to create serpent.xcodeproj from serpent/CMakeLists.txt as follows:
  
• For "Where is the source code:" and "Where to build the binaries:", use the serpent directory, e.g. /Users/rbd/serpent/64bit.
  
• Be sure to check USE_GLCANVAS, which may be a sub-menu item under "USE". (Alternatively, you can probably build wxWindows without the --with-opengl flag, in which case you should uncheck USE_GLCANVAS, and wxserpent will be built without OpenGL canvas and functions).
• There are other options:
• 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.
• HAVE_WX_PACKAGE -- if your system has wxWidgets installed, CMake should be able to automatically find the libraries and link to them, avoiding the need to build your own version of wxWidgets. To do this, check HAVE_WX_PACKAGE. This will probably use dynamic libraries for wxWidgets, so if you move the application to another system, it might fail unless you install the same version of wxWidgets libraries there.
• HAVE_ZMQ – if your system has ZeroMQ installed, check this to use it. (Works like HAVE_WX_PACKAGE.) But you probably want O2 instead of ZMQ.
• USE_MIDI -- include functions that access PortMidi library (see "Serpent and PortMidi").
• USE_NETWORK -- include functions that access network functions (see "Network Interface and Functions").
  
• USE_O2 -- include functions that access O2.
• USE_OSC -- include functions that access Open Sound Control (see "Open Sound Control"). But now, O2 provides OSC functions, so you probably want this option OFF.
• USE_LIBLO -- only matters if USE_OSC is checked. Not recommended unless you need to parse incoming messages with timestamps and/or bundles (but O2 does this, so just forget liblo).
• USE_STATIC_LIBS -- recommended. If not checked, will try to use existing libraries. In principle, this could save work installing and building libraries from sources, e.g. wxwidgets and portmidi, but if the build fails, you should USE_STATIC_LIBS to reduce possible version and path problems.
  
• USE_PROC -- include functions that support a second real-time "process" (see "Proc Interface and Functions"). Probably you want this OFF.
• USE_ZMQ -- (not tested with Xcode 10) include zmq support (see "ZeroMQ"). Probably you want this OFF – use O2 instead.
  
• change WX_VERSION to 3.2
  
• consider setting CMAKE_OSX_DEPLOYMENT_TARGET and CMAKE_OSX_SYSROOT to use a particular version of the SDK. If you compile with a 10.14 SDK you cannot run on 10.7, for example. These number should be coordinated with the numbers in the command line to wxWidget's configure.
• Press configure (button)
• After the configure button (the first time), a window prompts for: "Specify the generator for this project." Select "Xcode" from a drop-down box.
• Click the Done button.
• Press configure (button) again.
• One possible error will complain "There is no SDK with the name or path '/Developer/SDKs/MacOSX14.6.sdk'. See installation-mac64-2019.htm for a solution.
• Press Generate.
• Do not change the AURA_DEF value from FALSE.
  
• Find WX_BASE_PATH. Set the value to your wxWidgets folder where you installed wxWindows. E.g. my Value string is "/Users/rbd/wxWidgets-3.1.3/" (without the quotes).
• Find WX_VERSION. This should match the prefix of the version you are actually using, e.g. use 3.1 for wxWidgets 3.1.3.
• This generates serpent/64bit.xcodeproject
• If you use Mac ports, there might be a conflict between the iconv library for Xcode and the one installed by Mac ports. To solve this problem, see installation-mac64-2019.htm.
• To control whether you build a debug version or release version, I use Xcode's Product:Scheme:Edit Scheme.. menu. In the dialog box, under Info, set Build Configuration to either Debug or Release.
• To make your installation look like the downloaded binaries, move wxserpent64.app to serpent:

  mv ~/serpent/64bit/wxsbuild/Release/wxserpent64.app ~/serpent
  

  (Otherwise, you can set things up to run directly from serpent/64bit/wxsbuild/Release/.)
• Now that you have compiled executables, you can follow the instructions above for installing them.