# Installing Pure Data

This README file contains info for installing Pure Data from source.

Pd is built on the commandline using traditional Unix-style tools. The source
distribution comes with two build systems:

* autotools: easy to use, many compilation options, recommended for most users
* makefile: smaller & simpler, used for Pd binary downloads

## Requirements

Core build requirements:

* Unix command shell: bash, dash, etc
* C compiler chain: gcc/clang & make

Core runtime requirements:

* Tcl/Tk: Tk wish shell

Optional features:

* autotools: autconf, automake, & libtool (if building with the autotools)
* gettext: build localizations in the po directory
* JACK: audio server support
* FFTW: use the optimized FFTW Fast Fourier Transform library

## Autotools Build (recommended)

Building Pd using the GNU autotools involves the following steps:

1. configure: detect & set library and platform options
2. make: compile Pd, associated tools, and resource files (ie. translations)
3. install: install the Pd binaries and resources onto your system

Overview:

    cd path/to/pd
    ./autogen.sh
    ./configure
    make

Start by opening a commandline shell and navigating to the Pd source directory:

    cd path/to/pd

First generate the configure script and various build files by running:

    ./autogen.sh

Next configure Pd with the default options for your platform:

    ./configure

You can verify the configuration options that the configure step script prints:

    pd 0.47.1 is now configured

    Platform:             Mac OSX
    Debug build:          no
    Universal build:      no
    Localizations:        no
    Source directory:     .
    Installation prefix:  /usr/local

    ...

    audio APIs:           PortAudio
    midi APIs:            PortMidi

If you want to change these options, you can specify/override the configure
script settings on the commandline:

    # change install prefix to /usr
    ./configure --prefix /usr

    # build Pd with the JACK audio server backend
    ./configure --enable-jack 

    # build Pd using a system installed PortAudio
    ./configure --without-local-portaudio

An important configure option is --enable-universal which allows you to specify
the desired architecture(s) when building Pd. For Intel/AMD processors, 32 bit
is called "i386" and 64 bit is "x86_64". By default, Pd is built for the
architecture of the current system, however you may want a 32 bit Pd to work
with existing 32 bit externals on a 64 bit system. You can override the defaults
with --enable-universal:

    # build 32 bit Pd
    ./configure --enable-universal=i386

    # build 64 bit Pd
    ./configure --with-universal=x86_64

    # build a "fat" Pd for both 32 and 64 bit (not useful on all platforms)
    ./configure --enable-universal=i386,x86_64

    # build a "fat" Pd for all detected architectures (macOS: i386, x86_64, ppc)
    ./configure --enable-universal

The full list of available configuration options can printed by running: 

    ./configure --help

Now that Pd is configured, build by running:

    make

Building should take a minute or two. If compilation was successful, you can
run Pd from the build directory without installing it:

    cd bin
    ./pd

To install to your system using the configuration prefix (default /usr/local):

    sudo make install

You can also to a custom location via:

    make install DESTDIR=~/pd-xxx prefix=/

Once installed, you should now be able to run Pd from the commandline:

    pd

If want to uninstall, make sure Pd is configured and then run:

    sudo make uninstall

If you compiled Pd using the --enable-universal configure option and want to
double check which architectures Pd was built with, use the "file" command:

    # examine binary in the src directory
    file src/pd
    ...
    src/pd: Mach-O 64-bit executable x86_64

    # look at pd inside a macOS .app bundle
    file Pd.app/Contents/Resources/bin/pd
    ...
    Pd-0.47.1.app/Contents/Resources/bin/pd: Mach-O 64-bit executable x86_64

### Linux & BSD

Platform requirements:

* ALSA: Linux sound library (recommended)
* OSS: historical precursor to ALSA, generally not used
* JACK: JACK audio server (optional)

Install the core build requirements using your distribution's package manager.
For Debian, you can install the compiler chain, autotools, & gettext with:

    sudo apt-get install build-essentials automake autoconf libtool gettext

For libraries, you will need to install the "development" versions which include
the source code header files. In Debian, the ALSA development package is called
"libasound2-dev":

    sudo apt-get install libasound2-dev

Similarly, optional development libraries can be also be installed to for
additional features. Install the JACK development files on Debian:

    sudo apt-get install libjack-jackd2-dev

In case you are using jackd1 instead of jackd2, use:

    sudo apt-get install libjack-dev

Most distributions come with Tcl/Tk installed, so you should be able to run Pd
after it is built.

### macOS

macOS is built on top of a BSD system and the bash commandline can be accessed
with the Terminal application in the /Applications/Utility directory.

The clang compiler and associated tools are provided by Apple. If you are
running macOS 10.9+, you *do not* need to install the full Xcode application and
can install the Commandline Tools Package only by running the following:

    xcode-select --install

If you are running macOS 10.6 - 10.8, you will need to install Xcode
from the Mac App Store or downloaded from http://developer.apple.com

Tcl/Tk is already included macOS.

To install the autotools, gettext, and libraries for additional features,
you can use one of the open source package managers for macOS:

* homebrew: https://brew.sh (recommended)
* macports: https://www.macports.org

Follow the package manager set up instructions and then install the software you
need. For example, to install the autotools & gettext using Homebrew:

    brew install automake autoconf libtool pkg-config gettext
    brew link --force gettext

By default, Pd is built for the current system architecture, usually 64 bit. If
you want to override this you can use the --enable-universal configure option,
as mentioned in the main Autotools Build section. On macOS, running this option
without arguments will build Pd for all architectures supported by the compiler:

* 10.6: i386, x86_64, ppc
* 10.7+: i386, x86_64

The JACK audio server is supported by Pd on macOS. By default, Pd can use the
Jack OS X runtime framework from http://www.jackosx.com if it is installed on
the system. Optionally, Pd can also be built with Jack installed via Homebrew or
Macports, however the runtime framework support must be disabled:

    brew install jack
    ./configure --without-jack-framework

You should now be ready to build Pd. Once built, there are two options for
installation:

* build a standalone macOS application (recommended)
* install to your system as a commandline program

To build the Pd macOS application, simply run:

    make app

This builds Pd-#.#.#.app in the Pd source directory which can be then be
double-clicked and/or copied to /Applications. For more info &
options regarding the Pd .app bundle, see mac/README.txt

If you want to have both the Pd application *and* use Pd from the commandline,
add command aliases to the binaries inside the .app to your ~/.bash_profile:

# pd commandline
WHICHPD="Pd-0.47-1"
alias pd="/Applications/$WHICHPD.app/Contents/Resources/bin/pd"
alias pdsend="/Applications/$WHICHPD.app/Contents/Resources/bin/pdsend"
alias pdreceive="/Applications/$WHICHPD.app/Contents/Resources/bin/pdreceive"

Next, reload the profile by either opening a new Terminal window or running:

    source ~/.bash_profile

If you install Pd to your system with "make install", the Tk 8.5.9
currently included with the system is buggy and should *not* be used. It is
recommended to install a newer version, either via Homebrew or from the
ActiveState Tcl/Tk downloads.

To see which version the Pd GUI is using: set the log level to 3 & look for the
Tk version log line in the Pd window.

Another option is to set the Tk Wish command Pd uses to launch the GUI. At
start, Pd does a quick search in the "usual places" for Wish and chooses the
first path that exists. Currently, macOS also ships with Tcl/Tk 8.4 which works
fine and this wish can be invoked by Pd using the full path "/usr/bin/wish8.4".
You can configure Pd to use this search path first with:

    ./configure --with-wish=/usr/bin/wish8.4

To see Pd's path search info, run Pd with the -verbose flag:

    pd -verbose

Note: Pd installed to your system or run from the build/bin directory will not
use the default font and will be missing the various macOS GUI hints (such as
retina rendering) which are specified by the Info.plist file inside the .app
bundle. Again, it is recommended to build a .app and use the aforementioned
aliases to provide the pd command.

### Windows

*Windows-specific info goes here*

## Makefile Build

Alternatively, and often more simply, to the autotools build, you can use the
fallback makefiles in the src directory:

* src/makefile.gnu: GNU/Linux
* src/makefile.mac: macOS
* src/makefile.msvc: Windows with Microsoft Visual C
* src/makefile.mingw: Windows with MinGW GCC

On Linux, for example, run the GNU-specific makefile in the src directory:

    cd src
    make -f makefile.gnu

You can then run directly out of the bin directory without installing:

    cd ../bin
    ./pd

For Microsoft Visual C, first build Pd with the MS VC makefile and then build
each external in the extra directory:

    cd src
    make -f makefile.msvc
    cd ../extra/bob~
    make pd_nt
    cd ../bonk~ && make pd_nt
    cd ../choice && make pd_nt
    cd ../fiddle~ && make pd_nt
    ...

To install Pd to your system on Linux, macOS, & MinGW (Windows), use the
"install" makefile target. For Linux, this is:

    make -f makefile.gnu install

Once installed, you should now be able to run Pd from the commandline:

    pd

If want to uninstall, simply run the "uninstall" makefile target:

    make -f makefile.gnu uninstall

On macOS, you can build a clickable Pd .app bundle using the supplemental build
scripts in the mac directory. See mac/README.txt for more info.

## Reporting Bugs

Let us know if you run into any bugs or issues with building or installing Pd:

* send an email: https://lists.puredata.info/listinfo
* post to the Pd forum: https://forum.pdpatchrepo.info
* create a bugreport: https://bugs.puredata.info
* open an issue: https://github.com/pure-data/pure-data/issues

Please include information involved with your problem such as:

* information about your system: OS version, libraries installed, etc
* configure or make output including error lines
* steps you took: configuration options, etc