Building and installing Nsound¶
Binary installers¶
There are currently no binary installers.
Building The C++ Library From Source¶
A general overview of building Nsound from source is given here, with detailed instructions for specific platforms given separately.
Prerequisites¶
Building Nsound requires the following software installed:
Python 3.7 or later
On Debian and derivative (Ubuntu): python
On Windows: the official 64-bit Python installer at www.python.org is enough
On Mac OSX: I highly recommend the MacPorts package manager to install the latest versions of Python 3.7, Numpy and Matplotlib www.macports.org .
Scons
Nsound uses this execellent build system, www.scons.org .
python3 -m pip install scons
and install it by running the dist/scons*.exe file.
A C++ compiler
To build Nsound you will need a C++ compiler.
On Windows: you’ll need to install Visual Studio.
On Mac OS X: you’ll need to install XCode command line tools.
Optional Prerequisites¶
Matplotlib
For creating pretty plots, Matplotlib is used.
Numpy and python-dateutil are a prerequisites for Matplotlib.
python3 -m pip install matplotlib
PortAudio
To enable audio playback through the soundcard, Nsound can use portaudio.
PortAudio: www.portaudio.com
On Windows, portaudio have already been statically built and provided.
SWIG
To build the Python module, SWIG generates the Python wrapper code.
On Windows: you’ll download and unzip to
C:\
.
Testing that all Matplotlib dependancies are met¶
Usually this is only a problem for the Windows platform, since Linux and MacPorts download and install prerequisite automatically.
Start a Python Shell and import matplotlib:
>>> import matplotlib >>> # Try to import pyplot. >>> from matplotlib import pyplot >>> # Try to plot something >>> pyplot.plot([1,2,3,4], "bo-") >>> pyplot.show()
Compiling The C++ Library¶
Uncompress the Nsound archive:
$ tar xfz Nsound-0.9.5.tar.gz
Execute the SCons tool:
cd Nsound-0.9.5 scons
SCons will query your computer for specific information about the build environment and generate a few files. It will then proceed to build the Nsound library and examples.
To get help with scons, do:
$ scons --help
scons: Reading SConscript files ...
scons: Reading SConscript files ...
Building with 4 threads
scons: done reading SConscript files.
usage: scons [OPTION] [TARGET] ...
SCons Options:
-b, -d, -e, -m, -S, -t, -w, --environment-overrides, --no-keep-going,
--no-print-directory, --print-directory, --stop, --touch
Ignored for compatibility.
-c, --clean, --remove Remove specified targets and dependencies.
-C DIR, --directory=DIR Change to DIR before doing anything.
--cache-debug=FILE Print CacheDir debug info to FILE.
--cache-disable, --no-cache
Do not retrieve built targets from CacheDir.
--cache-force, --cache-populate
Copy already-built targets into the CacheDir.
--cache-readonly Do not update CacheDir with built targets.
--cache-show Print build actions for files from CacheDir.
--config=MODE Controls Configure subsystem: auto, force,
cache.
-D Search up directory tree for SConstruct,
build all Default() targets.
--debug=TYPE Print various types of debugging information:
count, duplicate, explain, findlibs, includes,
memoizer, memory, objects, pdb, prepare,
presub, stacktrace, time, action-timestamps.
--diskcheck=TYPE Enable specific on-disk checks.
--duplicate=DUPLICATE Set the preferred duplication methods. Must be
one of hard-soft-copy, soft-hard-copy,
hard-copy, soft-copy, copy
--enable-virtualenv Import certain virtualenv variables to SCons
--experimental=EXPERIMENTAL
Enable experimental features
-f FILE, --file=FILE, --makefile=FILE, --sconstruct=FILE
Read FILE as the top-level SConstruct file.
-h, --help Print defined help message, or this one.
-H, --help-options Print this message and exit.
--hash-chunksize=N, --md5-chunksize=N
Set chunk-size for hash signature computation to
N kilobytes.
--hash-format=HASH_FORMAT Hash format (e.g. md5, sha1, or sha256).
-i, --ignore-errors Ignore errors from build actions.
-I DIR, --include-dir=DIR Search DIR for imported Python modules.
--ignore-virtualenv Do not import virtualenv variables to SCons
--implicit-cache Cache implicit dependencies
--implicit-deps-changed Ignore cached implicit dependencies.
--implicit-deps-unchanged Ignore changes in implicit dependencies.
--interact, --interactive Run in interactive mode.
-j N, --jobs=N Allow N jobs at once.
-k, --keep-going Keep going when a target can't be made.
--max-drift=N Set maximum system clock drift to N seconds.
-n, --no-exec, --just-print, --dry-run, --recon
Don't build; just print commands.
--no-site-dir Don't search or use the usual site_scons dir.
--profile=FILE Profile SCons and put results in FILE.
-q, --question Don't build; exit status says if up to date.
-Q Suppress "Reading/Building" progress messages.
--random Build dependencies in random order.
-s, --silent, --quiet Don't print commands.
--site-dir=DIR Use DIR instead of the usual site_scons dir.
--stack-size=N Set the stack size of the threads used to run
jobs to N kilobytes.
--taskmastertrace=FILE Trace Node evaluation to FILE.
--tree=OPTIONS Print a dependency tree in various formats: all,
derived, prune, status, linedraw.
-u, --up, --search-up Search up directory tree for SConstruct,
build targets at or below current directory.
-U Search up directory tree for SConstruct,
build Default() targets from local SConscript.
-v, --version Print the SCons version number and exit.
--warn=WARNING-SPEC, --warning=WARNING-SPEC
Enable or disable warnings.
-Y REPOSITORY, --repository=REPOSITORY, --srcdir=REPOSITORY
Search REPOSITORY for source and target files.
Local Options:
--compiler=COMPILER Sets the install prefix for programs and
libraries
--extra-warnings Adds extra warning flags to CXXFLAGS
--disable-64 Disables float64 type, uses float32 instead
--disable-libao Disables the libao AudioBackend
--disable-libportaudio Disables the libportaudio AudioBackend
--enable-cuda Enables Cuda accelerated functions and linking
--disable-openmp Disables OpenMp accelerated functions and
linking
--disable-python Disables the use of matplotlib via Python, only
applies to C++ lib
--static Builds a static C++ lib
--prefix=PREFIX Sets the install prefix for programs and
libraries
--config-debug Prints lots of debug messages during scons
configuration tests
--V, --verbose Shows full compiler command output
--D, --DEBUG Compile in debug mode
--with-boost=BOOST_PREFIX Adds the boost include path into the compiler
flags
--pytest Rebuilds python module, then runs unit tests
--unit-test Runs the c++ unit tests
On Windows: Compiling Nsound From The Command Line¶
On Windows, rather than muck around with the System’s PATH environment variables, I recommend creating a .BAT file that will insert paths into the environment.
Save this file to your doesktop
windows_env64.bat
Create a shortcut to the file
windows_env64.bat
, edit the shortcut so the target line reads like this:cmd /k 'C:\Users\USERNAME\Desktop\windows_env64.bat'
replacing USERNAME with your username.
Modify the shortcut startup directory to be located in the nsound directory, this way you won’t have to cd to it all the time.
Double click the shortcut to open a DOS box with Visual Studio, Python, and SCons in the path, so building Nsound becomes as simple as:
C:\Users\USERNAME\code\nsound> scons
On Windows: Compiling Nsound C++ library Using Visual Studio¶
Before trying to compile Nsound with Vistual Studio, ensure that Python and SCons have been installed. There are Visual Studio build steps that will execute scons to generate some files.
Next, examine the file msvs\properties.props
to ensure the path to Python
is correct, the default is C:\Python310
.
A Visual Studio 2010+ solution file is provide in msvs\nsound.sln
. Debug
builds won’t link with Python because the debug library python310_d.lib
is
not provided, but isn’t needed if you’re debugging Nound C++ code.
Note
If you see this error:
LINK : fatal error LNK1181: cannot open input file ‘winmm.lib’
it may mean you are using “Visual Studio Express for Windows”. This error will go away if you install “Visual Studio Express for Windows Desktop”.
Cygwin Notes¶
If you run into an error message that looks something like:
python 6140 C:\cygwin\bin\python.exe: *** fatal error - unable to remap \\?\C:\cygwin\lib\python2.6\lib-dynload\time.dll to same address as parent: 0x2B0000 != 0x360000
You will need to “rebase” your Cygwin installation. To do so follow these steps:
Close all Cygwin programs that may be using the cygwin.dll
Ensure the Cygwin package called rebase is installed using the setup.exe program
Start a Windows DOS box (not a Cygwin shell)
Start an ASH shell, then run the rebaseall command by executing:
C:\> C:\cygwin\bin\ash.exe $ cd /bin $ ./rebaseall
Compiling the Python Module¶
Note
SWIG must be installed to generate the Python interface.
Try compiling the C++ library first to ensure SCons and the C++ compiler are working (see step 2 above in Compiling The C++ Library).
Build, install and test the Python module:
scons --pytest
Mac OSX Notes - Use MacPorts (TODO: Update for python 3.7+)¶
To enable real-time playback and plottting, install these prerequisites using the mac port project:
sudo port install swig scons py27-matplotlib portaudio swig-python py27-game py27-pip
Select the macport version of python and pip the defaults:
sudo port select python python27
sudo port select pip pip27
Linking With A Python Installed In A Non-Standard Location¶
Sometimes a custom built Python is installed in a non-standard location, for example:
/usr/local/python2.7
You will need to install scons to this non-stanard location, then just run scons with this non-standard python:
/usr/local/python2.7/bin/scons
The SCons build environment will ask Python’s distutils
module for the
location of the include directory and dynamic library paths. This should get
done automatically. A SCons tool was added to brute-force check the
distutils
build variables to locate these paths,
site_scons/site_tools/ImportPythonConfig.py
. To enable some extra
debug messages, try using the --config-debug
switch with scons:
scons --config-debug
Please report any problems you are having to Nick.
Python Errors¶
Sometime everything above goes well, SCons finds the libraries, compiles and links everything fine, but at runtime you may run into other errors.
Matplotlib Backend Not Set¶
You may see a message like:
Traceback (most recent call last):
File "/usr/local/python2.7/lib/python2.7/site-packages/matplotlib/backends/__init__.py", line 35, in do_nothing_show
fname = frame.f_back.f_code.co_filename
AttributeError: 'NoneType' object has no attribute 'f_code'
src/Nsound/Plotter.cc:171: failed to call python pylab.show()
This is due to the Matplotlib Backend not being set. So set a default backend edit the file matplotlibrc, and set the following:
backend : BACKEND
and replace BACKEND with something like GTKAgg, GTKCairo, CocoaAgg, MacOSX, QtAgg, WXAgg. The choice depends on the backends that are installed. To test if a specific backend is installed do:
>>> import matplotlib
>>> matplotlib.use("GTKAgg") # Specify specific backend
>>> import matplotlib.pylab
>>> pylab.plot([1,2,3,4,3,2,1])
>>> pylab.show() # Plot will appear if you selected a working GUI backend
>>> pylab.savefig("somefile.png") # Replace png with pdf or svg to
... # to test a file only backend
You should either see a figure window show up after the show() call or a filename written to the local directory after the savefig() call.
Installing The Nsound Python Module Via PIP¶
All the prerequisites still apply from above. With pip you won’t have to download the Nsound source code yourself.
From a shell with your build environment setup, do:
python3 -m pip install Nsound