Compilation

Compilation should be working on Linux, Windows with MinGW and Mac OS X. You will need header files of Puredata, as well as libcurl, json-c, and liboauth.

The package build script uses the Makefile template from pd-lib-builder.

To enable multi-instance support, add multi=true to the make command.

If you have gotten the source code from git, you will first have to init the uthash and pd-lib-builder submodule by running git submodule update --init.

OS X and Linux build scripts do not include dependencies in the resulting pd_linux or pd_darwin files. For making a distributable version of the library, there is a collection of bash scripts for the different platforms.

The manual is generated from the Github wiki. To generate it as well, a copy of the wiki is necessary (get it via git clone https://github.com/residuum/PuRestJson.wiki.git). The python script is called create_manual.py and needs grip and BeautifulSoup. Install those via pip install grip beautifulsoup lxml.

Circle CI Builds - General Information

PuREST JSON is configured to build on Circle CI. The bash scripts in the folder circleci-scripts may serve as secondary documentation for building:

• */before_install.sh sets up the build environment
• */script.sh is the command to build the binaries
• */pack.sh generates the manual and creates deken packages
• upload.sh uploads the resulting package to my personal ownCloud instance

Linux

As a guideline, look at the scripts in the circleci-scripts/linux-amd64 folder, as the scripts in forder linux-i386 are used to build 32 bit i386 packages on a 64 bit amd64 system.

1. You need build-essentials, header files for puredata, libjson-c, libcurl4, liboauth. If you have Debian or a derivative (e.g. Ubuntu, Linux Mint), you can install the build utils and needed headers with apt-get install build-essential puredata-dev libjson-c-dev libcurl4-openssl-dev liboauth-dev. If you are not root, prefix the command with sudo.
2. Drop the sources in a directory and run make. You will get files with a suffix of pd_linux for each object (json-decode.pd_linux, json-encode.pd_linux, rest.pd_linux, oauth.pd_linux). These are needed to use the library.
3. (optional) To create a distributable version, you have to install patchelf, e.g. apt-get install patchelf. Run bash dependencies/linux.sh *.pdlinux. This will copy dependencies to the current folder and rewrite linking information in the files to point to these dependencies.

Building for Different Architectures

Building for different architectures is possible. I will outline a way to do it on Debian based systems, e.g. Ubuntu.

1. Install debootstrap, e.g. via apt-get install debootstrap.
2. Set up a directory as the root for your new chroot, e.g. for /tmp/buildroot on Ubuntu Trusty for i386 with

   sudo debootstrap \
       --variant=buildd \
      	--include=build-essential \
       --arch=i386 \
       trusty /tmp/buildroot http://archive.ubuntu.com/ubuntu/

3. Install the basic build system in that directory, and install the necessary dependencies for that architecture e.g. with

   echo deb http://archive.ubuntu.com/ubuntu/ \
       $DIST restricted universe multiverse \
       | sudo tee -a /tmp/buildroot/etc/apt/sources.list
   sudo chroot /tmp/buildroot bash -c "apt-get update"
   sudo chroot /tmp/buildroot bash -c "apt-get install -qq -y build-essential \
       puredata-dev libjson-c-dev libcurl4-nss-dev liboauth-dev"

4. Copy the files to a subfolder in the chroot folder, e.g. /tmp/buildroot/PuRestJson
5. Run make via chroot:

   sudo chroot /tmp/buildroot bash -c "cd PuRestJson && make"

6. (optional) To create a distributable version, you have to install patchelf, e.g. sudo chroot /tmp/buildroot bash -c "apt-get install patchelf". Run sudo chroot ${CHROOTDIR} bash -c "cd PuRestJson && bash ./dependencies/linux.sh *.pd_linux". This will copy dependencies to the /tmp/buildroot and rewrite linking information in the files to point to these dependencies.

Windows with MinGW

This is possible, but I have given up on it, and only cross-compile the library with MXE.

Compilation on Mac OS X

As a guideline, look at the scripts in the circleci-scripts/osx folder.

1. Install XCode, and install the command line tools to get gcc and otool.
2. Install Homebrew to later install the dependencies.
3. Install dependencies via Homebrew:

   brew update
   brew install json-c curl liboauth --universal

4. Find the path to Pd.
5. Drop the sources in a directory and run make pdincludepath=/path/to/pd/Contents/Resources/src
6. (optional) You are now able to use the library on a machine, if the dependencies are installed via Homebrew. To move the necessary dylibs to the current directory and change the links of the pd_darwin files, run ./dependencies/osx.sh. This makes the whole folder distributable.

Cross-compilation for Windows on UNIX-like systems (Linux / *BSD / Mac OS X) with MXE

As a guideline, look at the scripts in the circleci-scripts/windows32 folder.

1. Get the development version of MXE from their Github repository and setup MXE, so that the cross compilation tools are in your PATH environmental variable.
2. Build the required libraries by running make curl json-c liboauth pthreads.
3. Download the Windows version of Pd and unzip it in a folder. You should have the following structure of files:

   pd/src/(source files including m_pd.h)
   pd/bin/pd.dll

4. Run make with some environmental variables to tell the compiler to use the cross compiler, and where to find the Pd source and pd.dll. Here is an example from my setup:

   #!/bin/bash
   MXE_DIR=/usr/lib/mxe
   MXE_GCC=${MXE_DIR}/usr/bin/i686-w64-mingw32.static-gcc
   PD_DIR=/tmp/pd
   
   make \
     system=Windows \
     machine=i386 \
     uname=MINGW \
     pdincludepath=${PD_DIR}/src \
     pdbinpath=${PD_DIR}/bin \
     CC=${MXE_GCC} \
     arch.c.flags='-march=pentium4 -msse -msse2 -mfpmath=sse -I \
       "/usr/lib/mxe/usr/i686-w64-mingw32.static/include"' \
     ldflags='-L "/usr/lib/mxe/usr/i686-w64-mingw32.static/lib"'