Installation Notes for Serpent on 64-bit Windows

Roger B. Dannenberg

There are two versions of serpent; one is a command line program and the other is a graphical interface program:

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

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

serpent-win-nnn.exe - Windows installer: serpent64.exe, wxserpent64.exe, and serpent libraries
serpent-src-nnn.zip - Source code for any platform (Linux, Windows, OS X)
(serpent-mac-nnn.zip - Mac OS X (32 bit) executable and bundle: serpent and wxserpent.app)

The "win" exe is an installer with pre-compiled programs. The "src" zip file contains sources for all platforms: see "Building From Sources" below.

Installing Compiled Programs

You should be able to simply download serpent-win-nnn.exe to your machine and run it to install serpent64 and wxserpent64. The installer will also set the registry with a search path to serpent libraries (lib, programs, and wxslib are on the path). The installer will also ask permission to add the installation directory to your Windows environment Path variable, but the setting does not take effect until you log out and log in again.
The executables are (for Windows): serpent64.exe and wxserpent64.exe.

Three things to keep in mind:

Both serpent64 (a command line program) and wxserpent64 (serpent with graphical toolkit) should be run from the command line.
To run an executable from a command line, your system must be able to find it. The installer will modify your Path. If you move the installed code (default is in Program Files (x86)\Serpent), you will need to update the Path as well:

Open Control Panel: Systems and Maintenance: System: Advanced System Settings. Click on the "Advanced" tab, then the "Environment Variables" button. Under "User variables," edit the value for Path.

You also need a path for Serpent (called SERPENTPATH). The installer will try to set SERPENTPATH (without asking). Indications are that Windows 8 blocks the installer, so you may have to do this step manually. Also, if you move the installation or want to add other directories, set the entry yourself. To manually change SERPENTPATH, go to (or create) the registry entry:
"My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\CMU\Serpent\"
and add a new string value there named "SERPENTPATH". Set the Data (value) to the path. On a default installation, this Data is "c:\Program Files (x86)\Serpent\lib\;c:\Program Files (x86)\Serpent\programs\;c:\Program Files (x86)\Serpent\wxslib". (The quotes are not part of the Data.) To set this, go to the Start menu and select "Run...", then type in "Registry Editor" and click "OK". Use this editor to create and set the path. The Registry Editor program gives you access to all kinds of critical internal settings for your machine. Be careful.

Testing:

Run serpent64 from a command prompt:

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

This will run the init.srp in lib, which is a good simple test.

Try

wxserpent64 wxs_test.srp

to test wxserpent64 and see a variety of input controls. The screen will look something like this:

Building From Sources

Get Serpent source code. If you want 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. If you install liblo, for example, you should have liblo in the parent directory of serpent, i.e. it will be serpent/../liblo.

I use Tortoise SVN and Microsoft Visual Studio Community 2017 v.15.5.4 for Windows on Windows 10 Pro. Here's how I build from sources on Windows. First, I list all the things to download; then, I give instructions on what and how to build:

Download wxWidgets from wxWidgets 3.1.2 (only necessary for wxserpent). I used the installer and put it in C:/wxWidgets-3.1.2
If you do not have Microsoft Visual Studio Community 2017 for Windows, you can install a free version.
Serpent has an optional interface to PortMidi. To enable this (recommended), you will need to download and build PortMidi:
- make a directory called portmidi at the same level as the serpent directory.
- Download or clone sources from PortMidi into portmidi.
- Download pthreads-win32-2-9-1-release.zip. (Look near the bottom of the list of files.)
- un-archive the files to pthreads (at the same level as serpent). The result should be, e.g. C:/Users/rbd/serpent, C:/Users/pthreads/pthreads.2
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 to download liblo:
- (Not recommended) 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.
Download O2 from the O2 repository on github. The main o2 directory should have the same parent as serpent, e.g. if you have C:/Users/rbd/serpent, then you should have C:/Users/rbd/o2/src/o2.h.
(Not recommended unless you need ZeroMQ functions) Download and unzip the file. You should have a folder named zeromq-4.1.4 containing a folder also named zeromq-4.1.4. Rename the innermost folder ZeroMQ and move it to the same level as serpent, e.g. /home/rbd/ZeroMQ, /home/rbd/serpent. Notice the directory name ZeroMQ is not ZeroMQ-4.1.4 or any default name. Within ZeroMQ, after installation, you should find builds/msvc/msvc.sln. (Ignore builds/msvc/msvc10.sln).

(Only if you are including ZeroMQ functions) Download libsodium (required by ZeroMQ). From Index of /libsodium/releases/, I downloaded libsodium-1.0.13-msvc.zip, opting for a pre-compiled library. Extract the files into libsodium at the same level as serpent.

Download freeglut (required for OpenGL capabilities in wxserpent). From Freeglut 3.0.0, get freglut-3.0.0.tar.tz and extract it (in 2 steps, I used 7-Zip). The main freeglut-3.0.0 directory should have the same parent directory as serpent. There should be freeglut-3.0.0/CMakeLists.txt there.

Check directory structure. You should now have a number of new directories all at the same level as serpent. E.g. my directories include:

C:/Users/rbd/serpent
C:/Users/rbd/portmidi
C:/Users/rbd/freeglut-3.0.0
C:/Users/rbd/libsodium
C:/Users/rbd/zeromq-4.1.4
C:/Users/rbd/o2

Build FreeGLUT library.

Open freeglut-3.0.0/CMakeLists.txt with CMake and select FREEGLUT_BUILD_STATIC_LIBS, FREEGLUT_PRINT_ERRORS, FREEGLUT_PRINT_WARNINGS, and INSTALL_PDB. Turn OFF FREEGLUT_BUILD_SHARED_LIBS.

Configure and Generate with CMake.

Open freeglut-3.0.0/freeglut.sln with Visual Studio.

Select Release and x64 near the top of the IDE.

Open Properties of freeglut_static project (right click). Under Configuration Properties, C/C++, Code Generation, Runtime Library, select Multi-threaded (/MT).

build freeglut_static.

Copy freeglut-3.0.0/include/GL/freeglut_ext.h to freeglut-3.0.0/include/GL/glext.h.

Important:For some reason (freeglut headers?), the linker will expect .lib files to be named freeglutd.lib and freeglut.lib, so find the static lib files in lib/Release and lib/Debug directories and rename them manually to freeglut.lib and freeglutd.lib, respectively.

Build wxWidgets libraries:

Open wxWidgets-3.1.2\build\msw\wx_vc15.sln in Visual Studio (tested with VS 2019).

Allow Visual Studio to update the solution to your version of Visual Studio. I took the default to upgrade the SDK version and platform toolset.

Select x64 configuration - use the drop-down menu with "win32" to select x64.

Select "Debug" for the debug version of wxSerpent, or "Release" for the release version.

For the Release version (needed for the Release version of Serpent), go to each project and change code generation from /MD to /MT (Multithreaded -- static, not DLL).

Open the Batch Build window, click the Solution Config column to bring all the "Release|x64" configurations to the top, and select them. Click Build button.

If you plan to build a Debug versison of wxSerpent64, be sure to build a Debug version of wxWidgets as well.

You must install CMake.

Build PortMidi

When you first open portmidi/CMakeLists.txt, tell CMake to generate for Win64. Otherwise, it seems that some files might be put in an x64 subfolder, confusing other scripts.

Build PortMidi in Visual Studio: open portmidi.sln (created by CMake); Batch build; Select All; Build

(Not recommended) Build liblo if you want to use it (I recommend not; if not, you'll use a built-in OSC implementation that does not support timestamps and bundles, but does have some features missing from liblo.

In the liblo/build directory, run in a command prompt window:
premake4 vs2008

In the liblo/build/vs2008 directory, open liblo.sln:
cd vs2008
start liblo.sln

Right click on the liblo project and select Properties.

In the properties dialog window:

Configuration Properties : C/C++ : General : Additional Include Directories and select "All Configurations". The value of "Additional Include Directories" (click at the right on "..." button to open an editor) should be:
../../lo
../../src
../..
../../../pthreads/pthreads.2

Select Configuration Properties : C/C++ : Code Generation and select the "ReleaseLib" Configuration. Set the Runtime Library to Multi-threaded (/MT).

Select Configuration Properties : General and select the "ReleaseLib" Configuration. Set the Output Directory to ..\..\lib\Release.

Select Configuration Properties : General and select the "DebugLib" Configuration. Set the Output Directory to ..\..\lib\Debug.

Select Configuration Properties : Librarian and select the "DebugLib" Configuration. Set the Output File to $(OutDir)\liblo.dll (change from $(OutDir)\liblo_d.dll)

Open Build : Batch Build... and select only DebugLib and ReleaseLib for project liblo

For Visual C++ 2008 Express Edition, I had to modify lo/lo_endian.h. My version is in serpent/src/lo_endian.h. You should back up or rename liblo/lo/lo_endian.h, then copy serpent/src/lo_endian.h to liblo/lo/lo_endian.h.

Click the Build button

Build O2

Run CMake and set the directories to the top-level o2 directory.

In CMake, since you have PortMidi installed, the BUILD_MIDI_EXAMPLE option can be set (it just builds an example included with O2).

Select BUILD_STATIC_LIB

Do not select BUILD_TESTS_WITH_LIBLO unless you installed liblo.

Use Generate to make a project. Check that the current generator is correct, e.g. Visual Studio 15 2107 Win64 project.

In Visual Studio, open o2/o2.sln

In Batch Build, select ALL_BUILD for Release and Debug versions. (You do not need to select anything else) and build.

Build ZeroMQ (only if you want ZMQ functions in Serpent. O2 is recommended for communication rather than ZMQ, so you can ignore this). Here’s the basic plan: With Batch Build, build libzmq for StaticDebug and StaticRelease. Copy the Debug version, which oddly might end up in ZeroMQ/lib/libzmq_d.lib to ZeroMQ/lib/Debug/zmq_s.lib. Copy the Release version, which oddly might end up in ZeroMQ/lib/libzmq.lib to ZeroMQ/lib/Release/zmq_s.lib. (The _s in these names is to avoid any confusion or search paths that might link to a dynamic library instead of the static one.) In detail:

Change Configuration Type in libzmq Property Pages : Configuration Properties : General to Static library (.lib).

This enables ZeroMQ clients to link to a static library.

Use the View/Solution Explorer menu item or CTRL+ALT+L to show the "solution."

Right click libzmq, select Properties to open the Properties window.

Select ReleaseLIB from the Configurations drop-down menu (upper left region in window).

Select x64 from the Platform drop-down menu (upper middle region in window).

Note: Configuration Properties : General : Configuration Type should be Static library (.lib). Configuration Properties : C-C++ : Code Generation : Runtime Library should be Multi-threaded (/MT).

Select DebugLIB from the Configurations drop-down menu.

Note: Configuration Properties : General : Configuration Type should be Static Library (.lib). Configuration Properties : C-C++ : Code Generation should be Multi-threaded Debug (/MTd).

Important: Now select "All Configurations" from the Configuration drop-down menu of the libzmq Property Pages dialog box. Click on "Additional Include Directories" and then the down arrow at the far right to view them. Click the <Edit...> selection and then the folder with asterisk ("new folder") icon. Then find the libsodium/include directory (you installed libsodium in the same directory as zeromq, so it should be there). After adding this directory (the default paths to libsodium are wrong), click OK to make the change.

Click OK

Use Build/Batch Build... menu item to open the Batch Build window, and check the StaticDebug x64 and StaticRelease x64 projects for libzmq. (Others will not build because libsodium will not be found. It might be possible to configure libsodium or libzmq to build these other projects, but they are not necessary.) Click the Build button.

Drag or move and rename ZeroMQ/bin/x64/Release/v141/static/libzmq.lib to ZeroMQ/lib/Release/zmq_s.lib.

Drag or move and rename ZeroMQ/bin/x64/Debug/v141/static/libzmq.lib to ZeroMQ/lib/Debug/zmq_s.lib.

Don't do this step: Drag or move and rename ZeroMQ/libzmq.dll to ZeroMQ/lib/Debug/zmq.dll.

Create libraries.txt: To find all these libraries you’ve been creating, Serpent uses libraries.txt. The content of this file depends on your computer, so libraries.txt is not in the source code. However, serpent/64bit/libraries-example.txt is in the sources as a template.

Copy serpent/64bit/libraries-example.txt to serpent/64bit/libraries.txt.

Edit serpent/64bit/libraries.txt, making sure all the library paths and names are valid for your computer.
If you do not have both Debug (DBG) and Release (OPT) versions of libraries, you can set both DBG and OPT versions, e.g. PM_DBG_LIB and PM_OPT_LIB to the same library file.

Normally, you would not build Serpent with ZMQ functions, so you do not need to define the ZMQ and SODIUM variables.

Be sure to set WX_VERSION to a 2-digit number, e.g. if you built v3.1.2 of wxWidgets, then set WX_VERSION to 31. Do not use v3.1.2 or 3.1 or v312. Only 31 will work (or 32 if you have version 3.2.x, etc.).

Build Visual C “Solution” file with CMake. CMake is run as an ordinary graphical interface application, e.g. from the Start menu.

For "Where is the source code:" and "Where to build the binaries:", use the serpent directory, e.g. C:/Users/rbd/serpent/64bit/.

Do not change AURA_DEF; the value field should be FALSE.

There are other options:

HAVE_ZMQ_PACKAGE should be OFF if you are are installing a local zmq library for Serpent rather than relying on an installed copy (but you can ignore this if you are not using ZMQ at all, which is recommended.)

LINE_EDITING should be OFF -- the line editing library does not exist for Windows.

NEED_WX_RESIZE_QUALITY should be OFF -- this has to do with wxWidgets configuration and compatibility.

USE_GLCANVAS should be ON.

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_MIDI -- include functions that access PortMidi library (see "Serpent and PortMidi"). Probably you will set this to ON.

USE_NETWORK -- include functions that access network functions (see "Network Interface and Functions"). Probably you will set this to ON.

USE_O2 -- recommended ON. Adds the interface to 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_PROC -- include functions that support a second real-time "process" (see "Proc Interface and Functions"). Probably you will set this to OFF. Note: If you enable USE_PROC, Serpent will need the pthreads library, which you probably installed because PortMidi needs it too. If you skipped the pthreads download and install, go back and do it.
USE_SHFILE -- enables some Windows functions, e.g. for copying directories recursively. Great stuff if you are using Serpent as a Windows system scripting language, but probably OFF.

USE_STATIC_LIBS -- recommended ON. 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_ZEROMQ -- include zmq support (see "ZeroMQ"). Probably you will set this OFF and use O2 instead.

VERBOSE_WARNINGS -- controls compiler flags; your choice.

WXS_STDOUT_WINDOW -- if set, wxserpent will open a window in the GUI for text output (e.g. Serpent print statements). WXS_STDOUT_WINDOW should be ON so that you can get output when debugging under Visual Studio, which will not show console output. On the other hand, if you run Arco programs from a command prompt, you will always get text output in the command prompt window, which makes the WXS_STDOUT_WINDOW display redundant, in which case OFF is a reasonable choice.

Configure (button).

When asked what to generate, pick your Visual Studio version with "Win64" after it.

Configure a couple of times more until the red error lines go away (or else maybe you'll have to diagnose the problem), and

Generate (button).

Compile serpent and wxserpent64. Open serpent64.sln with Visual Studio, select Debug or Release (at top) and x64, and build ALL_BUILD (or serpent if you are not building wxserpent). There may be some dependency problems, so if some things fail to build at first, try again. Note:If you are building a Debug version, you should have build Debug versions of all the libraries described above. If you are building a Release version, you should have built Release versions of all the libraries described above.

To run the debug version of serpent, you will need to copy ../portmidi/Debug/portmidi.dll to C:/windows/system32 or someplace where the DLL will be found.

Now that you have compiled executables, you can follow the instructions above for installing them.