| 1 |
<!DOCTYPE html> |
| 2 |
<HTML lang="en"> |
| 3 |
<HEAD> |
| 4 |
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| 5 |
<TITLE>Pd Manual - Chapter 6: Building Pd from source</TITLE> |
| 6 |
<meta http-equiv="content-type" content="text/html; charset=UTF-8"> |
| 7 |
<link rel="stylesheet" type="text/css" href="resources/pdmanual.css" media="screen"> |
| 8 |
<link rel="icon" href="resources/favicon.ico"> |
| 9 |
</HEAD> |
| 10 |
<BODY> |
| 11 |
|
| 12 |
<div class="nav nav-top"> |
| 13 |
<div class="nav-back"><A href="5.current.status.htm">< Chapter 5: Current status</A></div> |
| 14 |
<div class="nav-home"><A href="index.htm#s6">Table of contents</A></div> |
| 15 |
<div class="nav-forward"></div> |
| 16 |
</div> |
| 17 |
<div id="corpus"> |
| 18 |
|
| 19 |
<IMG id="logo" src="resources/icon.png" ALT="pd icon"> |
| 20 |
|
| 21 |
<H2>Chapter 6: Building Pd from source</H2> |
| 22 |
|
| 23 |
<P>This chapter offers in depth details on how to build Pd from its source code |
| 24 |
and install it on different operating systems (macOS, Linux, BSD & Windows).</P> |
| 25 |
|
| 26 |
|
| 27 |
<H3> <A href="#s6.1" id="s6.1"> 6.1. Requirements </A> </H3> |
| 28 |
|
| 29 |
<P>Pd is built on the commandline using traditional Unix-style tools. The source |
| 30 |
distribution comes with two build systems:</P> |
| 31 |
|
| 32 |
<ul> |
| 33 |
<li><b>autotools:</b> easy to use, many compilation options <b>(recommended for most users)</b></li> |
| 34 |
<li><b>makefile:</b> smaller & simpler, used for Pd binary downloads</li> |
| 35 |
</ul> |
| 36 |
|
| 37 |
<p>The core build requirements are:</p> |
| 38 |
|
| 39 |
<ul> |
| 40 |
<li>Unix command shell: bash, dash, etc</li> |
| 41 |
<li>C compiler chain: gcc/clang & make</li> |
| 42 |
</ul> |
| 43 |
|
| 44 |
<p>And a core runtime requirement is:</p> |
| 45 |
|
| 46 |
<ul> |
| 47 |
<li>Tcl/Tk: Tk wish shell</li> |
| 48 |
</ul> |
| 49 |
|
| 50 |
<p>Optional features:</p> |
| 51 |
|
| 52 |
<ul> |
| 53 |
<li>autotools: autoconf, automake, & libtool (if building with the autotools)</li> |
| 54 |
<li>gettext: build localizations in the po directory</li> |
| 55 |
<li>JACK: audio server support</li> |
| 56 |
<li>FFTW: use the optimized FFTW Fast Fourier Transform library</li> |
| 57 |
</ul> |
| 58 |
|
| 59 |
|
| 60 |
<H3> <A href="#s6.2" id="s6.2"> 6.2. General autotools build steps </A> </H3> |
| 61 |
|
| 62 |
<p>Building Pd using the GNU autotools involves the following steps for all platforms:</p> |
| 63 |
|
| 64 |
<ul> |
| 65 |
<li>1. configure: detect & set library and platform options</li> |
| 66 |
<li>2. make: compile Pd, associated tools, and resource files (ie. translations)</li> |
| 67 |
<li>3. install: install the Pd binaries and resources onto your system</li> |
| 68 |
</ul> |
| 69 |
|
| 70 |
<p>Overview:</p> |
| 71 |
|
| 72 |
<pre><code>cd path/to/pd |
| 73 |
./autogen.sh |
| 74 |
./configure |
| 75 |
make |
| 76 |
</code></pre> |
| 77 |
|
| 78 |
<p>Note: Additional platform-specific options and build targets are listed in following sections.</p> |
| 79 |
<p>Start by opening a commandline shell and navigating to the Pd source directory:</p> |
| 80 |
|
| 81 |
<pre><code>cd path/to/pd</code></pre> |
| 82 |
|
| 83 |
<p>First generate the configure script and various build files by running:</p> |
| 84 |
|
| 85 |
<pre><code>./autogen.sh</code></pre> |
| 86 |
|
| 87 |
<p>Next configure Pd with the default options for your platform:</p> |
| 88 |
|
| 89 |
<pre><code>./configure</code></pre> |
| 90 |
|
| 91 |
<p>You can verify the configuration options that the configure step script prints:</p> |
| 92 |
|
| 93 |
<pre><samp>pd 0.55.0 is now configured |
| 94 |
|
| 95 |
Platform: Mac OSX |
| 96 |
Debug build: no |
| 97 |
Universal build: no |
| 98 |
Localizations: no |
| 99 |
Source directory: . |
| 100 |
Installation prefix: /usr/local |
| 101 |
|
| 102 |
... |
| 103 |
|
| 104 |
audio APIs: PortAudio |
| 105 |
midi APIs: PortMidi</samp></pre> |
| 106 |
|
| 107 |
<p>If you want to change these options, you can specify/override the configure script settings on the commandline:</p> |
| 108 |
|
| 109 |
<pre><code># change install prefix to /usr |
| 110 |
./configure --prefix /usr |
| 111 |
|
| 112 |
# build Pd with the JACK audio server backend |
| 113 |
./configure --enable-jack |
| 114 |
|
| 115 |
# build Pd using a system installed PortAudio |
| 116 |
./configure --without-local-portaudio</code></pre> |
| 117 |
|
| 118 |
<p>If you need to run Pd through a debugger (like gdb), you can |
| 119 |
build Pd with debugging symbols using the "--enable-debug" flag.</p> |
| 120 |
|
| 121 |
<pre><code># build Pd with debugging information |
| 122 |
./configure --enable-debug</code></pre> |
| 123 |
|
| 124 |
<p>An important configure option for some platforms is <code>--enable-universal</code> which allows you to specify the desired architecture(s) when building Pd. For Intel and 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 <code>--enable-universal</code>:</p> |
| 125 |
|
| 126 |
<pre><code># build 32 bit Pd |
| 127 |
./configure --enable-universal=i386 |
| 128 |
|
| 129 |
# build 64 bit Pd |
| 130 |
./configure --with-universal=x86_64</code></pre> |
| 131 |
|
| 132 |
<p>You can compile a "Double precision" Pd (aka "Pd64") with:</p> |
| 133 |
|
| 134 |
<pre><code>./configure --with-floatsize=64</code></pre> |
| 135 |
|
| 136 |
<p>The full list of available configuration options can printed by running:</p> |
| 137 |
|
| 138 |
<pre><code>./configure --help</code></pre> |
| 139 |
|
| 140 |
<p>Now that Pd is configured, build by running:</p> |
| 141 |
|
| 142 |
<pre><code>make</code></pre> |
| 143 |
|
| 144 |
<p>Building should take a minute or two. If compilation was successful, |
| 145 |
in Linux, you can run Pd from the build directory without installing it:</p> |
| 146 |
|
| 147 |
<pre><code>cd bin |
| 148 |
./pd</code></pre> |
| 149 |
|
| 150 |
<p>You need to create an app so you can use your build in macOS and Windows.</p> |
| 151 |
|
| 152 |
<pre><code>make app</code></pre> |
| 153 |
|
| 154 |
<p>To install to your Linux system using the configuration prefix |
| 155 |
(default <code>/usr/local</code>), do:</p> |
| 156 |
|
| 157 |
<pre><code>sudo make install</code></pre> |
| 158 |
|
| 159 |
<p>You can also to a custom location via:</p> |
| 160 |
|
| 161 |
<pre><code>make install DESTDIR=~/pd-xxx prefix=/</code></pre> |
| 162 |
|
| 163 |
<p>Once installed, you should now be able to run Pd from the commandline:</p> |
| 164 |
|
| 165 |
<pre><code>pd</code></pre> |
| 166 |
|
| 167 |
<p>If want to uninstall, make sure Pd is configured and then run:</p> |
| 168 |
|
| 169 |
<pre><code>sudo make uninstall</code></pre> |
| 170 |
|
| 171 |
<p>If you compiled Pd using the <code>--enable-universal</code> configure |
| 172 |
option and want to double check which architectures Pd was built |
| 173 |
with, use the "file" command:</p> |
| 174 |
|
| 175 |
<pre><code># examine binary in the src directory |
| 176 |
$ file src/pd |
| 177 |
... |
| 178 |
src/pd: Mach-O 64-bit executable x86_64 |
| 179 |
|
| 180 |
# look at pd inside a macOS .app bundle |
| 181 |
$ file Pd.app/Contents/Resources/bin/pd |
| 182 |
... |
| 183 |
Pd-0.55.0.app/Contents/Resources/bin/pd: Mach-O 64-bit executable x86_64</code></pre> |
| 184 |
|
| 185 |
<p>More details specific to each platform follow next.</p> |
| 186 |
|
| 187 |
<H3> <A href="#s6.3" id="s6.3"> 6.3. Building Pd for Linux </A> </H3> |
| 188 |
|
| 189 |
<p>Platform requirements:</p> |
| 190 |
|
| 191 |
<ul> |
| 192 |
<li>ALSA: Linux sound library (recommended)</li> |
| 193 |
<li>OSS: historical precursor to ALSA, generally not used</li> |
| 194 |
<li>JACK: JACK audio server (optional)</li> |
| 195 |
</ul> |
| 196 |
|
| 197 |
<p>Install the core build requirements using your distribution's package manager. For Debian, you can install the compiler chain, autotools, & gettext with:</p> |
| 198 |
|
| 199 |
<pre><code>sudo apt-get install build-essential automake autoconf libtool gettext</code></pre> |
| 200 |
|
| 201 |
<p>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":</p> |
| 202 |
|
| 203 |
<pre><code>sudo apt-get install libasound2-dev</code></pre> |
| 204 |
|
| 205 |
<p>Similarly, optional development libraries can be also be installed to for additional features. Install the JACK development files on Debian:</p> |
| 206 |
|
| 207 |
<pre><code>sudo apt-get install libjack-jackd2-dev</code></pre> |
| 208 |
|
| 209 |
<p>In case you are using jackd1 instead of jackd2, use:</p> |
| 210 |
|
| 211 |
<pre><code>sudo apt-get install libjack-dev</code></pre> |
| 212 |
|
| 213 |
<p>Most distributions come with Tcl/Tk installed, so you should be able to run Pd after it is built.</p> |
| 214 |
<p>Once your build system is set up, you can follow the general autotools build steps to build Pd.</p> |
| 215 |
|
| 216 |
|
| 217 |
<H3> <A href="#s6.4" id="s6.4"> 6.4. Building Pd for BSD </A> </H3> |
| 218 |
|
| 219 |
<p>Building Pd for the various BSD variants is similar to the Linux way. |
| 220 |
The major difference is the used package manager (and the names of the packages), |
| 221 |
you’ll want to install.</p> |
| 222 |
|
| 223 |
<H4> <A href="#s6.4.1" id="s6.4.1"> 6.4.1. FreeBSD </A> </H4> |
| 224 |
|
| 225 |
<p>(Tested on FreeBSD-13)</p> |
| 226 |
|
| 227 |
<p>Install the core build requirements:</p> |
| 228 |
|
| 229 |
<pre><code>sudo pkg install gcc automake autoconf libtool gettext gmake |
| 230 |
</code></pre> |
| 231 |
|
| 232 |
<p>You may install one (or more) libraries (depending on your needs). |
| 233 |
It seems that with FreeBSD-13, there are ALSA and JACK packages available:</p> |
| 234 |
|
| 235 |
<pre><code>sudo pkg install alsa-lib jackit |
| 236 |
</code></pre> |
| 237 |
|
| 238 |
<p>Once your build system is set up, you can follow the general autotools build |
| 239 |
steps to build Pd, but make sure to use <code>gmake</code> (aka “GNU make”). |
| 240 |
The ordinary BSD <code>make</code> will not suffice!</p> |
| 241 |
|
| 242 |
<pre><code>./autogen.sh |
| 243 |
./configure --deken-os=FreeBSD MAKE=gmake |
| 244 |
gmake |
| 245 |
|
| 246 |
sudo gmake install |
| 247 |
</code></pre> |
| 248 |
|
| 249 |
<H4> <A href="#s6.4.2" id="s6.4.2"> 6.4.2. OpenBSD </A> </H4> |
| 250 |
|
| 251 |
<p>(Tested on OpenBSD-7)</p> |
| 252 |
|
| 253 |
<p>Install the core build requirements:</p> |
| 254 |
|
| 255 |
<pre><code>sudo pkg_add gcc automake autoconf libtool gettext-tools gmake |
| 256 |
</code></pre> |
| 257 |
|
| 258 |
<p>(If there are multiple versions for one or more of the packages, pick your |
| 259 |
favourite or the newest one).</p> |
| 260 |
|
| 261 |
<p>You may install one (or more) libraries (depending on your needs). |
| 262 |
It seems that with OpenBSD-7, there are only JACK packages available:</p> |
| 263 |
|
| 264 |
<pre><code>sudo pkg_add jack |
| 265 |
</code></pre> |
| 266 |
|
| 267 |
<p>By default, OpenBSD installs all its packages into <code>/usr/local/</code>, |
| 268 |
but the compiler does not look for headers resp. libraries in this directory. |
| 269 |
We can instruct autotools to automatically consider these directories |
| 270 |
by creating a file <code>/usr/local/share/config.site</code>:</p> |
| 271 |
|
| 272 |
<pre><code>cat | sudo tee /usr/local/share/config.site>/dev/null << EOF |
| 273 |
CPPFLAGS="-I/usr/local/include \$CPPFLAGS" |
| 274 |
LDFLAGS="-L/usr/local/lib \$LDFLAGS" |
| 275 |
EOF |
| 276 |
</code></pre> |
| 277 |
|
| 278 |
<p>Also, because OpenBSD allows to coinstall multiple versions of the autotools (with no “default”), |
| 279 |
we must specify which version we want to use:</p> |
| 280 |
|
| 281 |
<pre><code>export AUTOCONF_VERSION=$(ls -S /usr/local/bin/autoconf-* | sed -e 's|.*-||' | sort -n | tail -1) |
| 282 |
export AUTOMAKE_VERSION=$(ls -S /usr/local/bin/automake-* | sed -e 's|.*-||' | sort -n | tail -1) |
| 283 |
</code></pre> |
| 284 |
|
| 285 |
<p>Now that your build system is set up, you can follow the general autotools build |
| 286 |
steps to build Pd, but make sure to use <code>gmake</code> (aka “GNU make”). |
| 287 |
The ordinary BSD <code>make</code> will not suffice!</p> |
| 288 |
|
| 289 |
<pre><code>./autogen.sh |
| 290 |
./configure --deken-os=OpenBSD --enable-jack MAKE=gmake |
| 291 |
gmake |
| 292 |
|
| 293 |
sudo gmake install |
| 294 |
</code></pre> |
| 295 |
|
| 296 |
<H4> <A href="#s6.4.3" id="s6.4.3"> 6.4.3. NetBSD </A> </H4> |
| 297 |
|
| 298 |
<p>(Tested on NetBSD-9)</p> |
| 299 |
|
| 300 |
<p>Install the core build requirements:</p> |
| 301 |
|
| 302 |
<pre><code>sudo pkgin install gcc automake autoconf libtool gettext-tools gmake |
| 303 |
</code></pre> |
| 304 |
|
| 305 |
<p>You may install one (or more) libraries (depending on your needs). |
| 306 |
It seems that with NetBSD-9, there are JACK and ALSA packages available, |
| 307 |
but the ALSA packages seem to be broken. OSS appears to be built-in.</p> |
| 308 |
|
| 309 |
<pre><code>sudo pkgin install jack</code></pre> |
| 310 |
|
| 311 |
<p>By default, NetBSD installs all its packages into <code>/usr/pkg/</code>, |
| 312 |
but the compiler does not look for headers resp. libraries in this directory. |
| 313 |
We can instruct autotools to automatically consider these directories |
| 314 |
by creating a file ‘/usr/pkg/share/config.site’:</p> |
| 315 |
|
| 316 |
<pre><code>cat | sudo tee /usr/pkg/share/config.site>/dev/null << EOF |
| 317 |
CPPFLAGS="-I/usr/pkg/include \$CPPFLAGS" |
| 318 |
LDFLAGS="-L/usr/pkg/lib -Wl,-R/usr/pkg/lib \$LDFLAGS" |
| 319 |
EOF </code></pre> |
| 320 |
|
| 321 |
<p>Now that your build system is set up, you can follow the general autotools build |
| 322 |
steps to build Pd, but make sure to use <code>gmake</code> (aka “GNU make”). |
| 323 |
The ordinary BSD <code>make</code> will not suffice!</p> |
| 324 |
|
| 325 |
<pre><code>./autogen.sh |
| 326 |
./configure --deken-os=NetBSD --prefix=/usr/pkg --disable-alsa --enable-jack MAKE=gmake |
| 327 |
gmake |
| 328 |
|
| 329 |
sudo gmake install |
| 330 |
</code></pre> |
| 331 |
|
| 332 |
|
| 333 |
<H3> <A href="#s6.5" id="s6.5"> 6.5. Building Pd for macOS </A> </H3> |
| 334 |
|
| 335 |
<p>macOS is built on top of a BSD system and the bash commandline |
| 336 |
can be accessed with the Terminal application in the |
| 337 |
<code>/Applications/Utility</code> directory.</p> |
| 338 |
|
| 339 |
<p>The clang compiler and associated tools are provided by Apple. |
| 340 |
If you are running macOS 10.9+, you <em>do not</em> need to install |
| 341 |
the full Xcode application and can install the Commandline Tools |
| 342 |
Package only by running the following:</p> |
| 343 |
|
| 344 |
<pre><code>xcode-select --install</code></pre> |
| 345 |
|
| 346 |
<p>For macOS versions earlier than 10.9, you will need to install |
| 347 |
Xcode from the Mac App Store or downloaded |
| 348 |
from <a href="http://developer.apple.com" target="_blank">http://developer.apple.com</a></p> |
| 349 |
|
| 350 |
<p>Tcl/Tk is already included macOS.</p> |
| 351 |
|
| 352 |
<p>To install the autotools, gettext, and libraries for additional |
| 353 |
features, you can use one of the open source package managers for macOS:</p> |
| 354 |
|
| 355 |
<ul> |
| 356 |
<li>homebrew: <a href="https://brew.sh" target="_blank">https://brew.sh </a>(recommended)</li> |
| 357 |
<li>macports: <a href="https://www.macports.org" target="_blank">https://www.macports.org</a></li> |
| 358 |
</ul> |
| 359 |
|
| 360 |
<p>Follow the package manager set up instructions and then install the |
| 361 |
software you need. For example, to install the autotools & gettext |
| 362 |
using Homebrew:</p> |
| 363 |
|
| 364 |
<pre><code>brew install automake autoconf libtool pkg-config gettext |
| 365 |
brew link --force gettext</code></pre> |
| 366 |
|
| 367 |
<p>By default, Pd is built for the current system architecture, usually 64 bit. If you want to override this you can use the <code>--enable-universal</code> configure option 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". For Apple Silicon processors (M1, M2, etc), the 64 bit architecture is called "arm64". 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 <code>--enable-universal</code>: you want to override this you can use the <code>--enable-universal</code> configure option, as mentioned in the main Autotools Build section. On macOS, running this option without arguments will build a "fat" Pd for all architectures supported by the compiler:</p> |
| 368 |
|
| 369 |
<ul> |
| 370 |
<li>macOS 10.6: i386, x86_64, ppc</li> |
| 371 |
<li>macOS 10.7+: i386, x86_64</li> |
| 372 |
<li>macOS 10.15: x86_64</li> |
| 373 |
<li>macOS 11+: x86_64, arm64</li> |
| 374 |
</ul> |
| 375 |
|
| 376 |
<p>Note: a "fat" Pd may not work on all systems and/or be |
| 377 |
able to load both 32 or 64 bit externals. Additionally, you can specify |
| 378 |
multiple architectures directly:</p> |
| 379 |
|
| 380 |
<pre><code># build a "fat" Pd for both 32 and 64 bit Intel |
| 381 |
# may not work on all systems |
| 382 |
./configure --enable-universal=i386,x86_64 |
| 383 |
|
| 384 |
# build a "fat" Pd for all detected architectures (macOS: i386, x86_64, ppc) |
| 385 |
# may not work on all systems |
| 386 |
./configure --enable-universal</code></pre> |
| 387 |
|
| 388 |
<p>The JACK audio server is supported by Pd on macOS. By default, |
| 389 |
Pd can use either the official 64-bit builds for macOS 10.12+ |
| 390 |
from <a href="https://jackaudio.org" target="_blank">https://jackaudio.org</a> |
| 391 |
or the older, 32-bit Jack OS X runtime framework if one is installed on the system. |
| 392 |
Optionally, Pd can also be built with Jack installed via Homebrew or Macports, |
| 393 |
however the runtime framework support must be disabled: </p> |
| 394 |
|
| 395 |
<pre><code>brew install jack |
| 396 |
./configure --disable-jack-framework --enable-jack</code></pre> |
| 397 |
|
| 398 |
<p>You should now be ready to build Pd by following the general autotools |
| 399 |
build steps. Once built, there are two options for installation:</p> |
| 400 |
|
| 401 |
<ul> |
| 402 |
<li>build a standalone macOS application (recommended)</li> |
| 403 |
<li>install to your system as a commandline program</li> |
| 404 |
</ul> |
| 405 |
|
| 406 |
<p>To build the Pd macOS application, simply run:</p> |
| 407 |
|
| 408 |
<pre><code>make app</code></pre> |
| 409 |
|
| 410 |
<p>This builds Pd-#.##.#.app in the Pd source directory which can be then be double-clicked |
| 411 |
and/or copied to <code>/Applications</code>. For more info & options regarding the Pd .app bundle, |
| 412 |
see <a href="6.building.from.source.htm#s6.5.1"> 6.5.1. macOS app bundle</a>.</p> |
| 413 |
|
| 414 |
<p>If you want to have both the Pd application <em>and</em> use Pd from the commandline, |
| 415 |
add command aliases to the binaries inside the .app to your <code>~/.bash_profile</code>:</p> |
| 416 |
|
| 417 |
<pre><code>WHICHPD="Pd-0.55-0" |
| 418 |
alias pd="/Applications/$WHICHPD.app/Contents/Resources/bin/pd" |
| 419 |
alias pdsend="/Applications/$WHICHPD.app/Contents/Resources/bin/pdsend" |
| 420 |
alias pdreceive="/Applications/$WHICHPD.app/Contents/Resources/bin/pdreceive" |
| 421 |
</code></pre> |
| 422 |
|
| 423 |
<p>Next, reload the profile by either opening a new Terminal window or running:</p> |
| 424 |
|
| 425 |
<pre><code>source ~/.bash_profile</code></pre> |
| 426 |
|
| 427 |
<p>If you install Pd to your system with "make install", the Tk 8.5.9 currently included with the system (as of macOS 10.14) is buggy and should <em>not</em> be used. It is recommended to install a newer version, either via Homebrew or from the ActiveState Tcl/Tk downloads.</p> |
| 428 |
|
| 429 |
<p>To see which version the Pd GUI is using: set the log level to 4 & look for the Tk version log line in the Pd window.</p> |
| 430 |
|
| 431 |
<p>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. Versions of macOS up to 10.12 also ship with Tcl/Tk 8.4 which works fine and this wish can be invoked by Pd using the full path <code>/usr/bin/wish8.4</code>. You can configure Pd to use this search path first with:</p> |
| 432 |
|
| 433 |
<pre><code>./configure --with-wish=/usr/bin/wish8.4</code></pre> |
| 434 |
|
| 435 |
<p>To see Pd's path search info, run Pd with the -verbose flag:</p> |
| 436 |
|
| 437 |
<pre><code>pd -verbose</code></pre> |
| 438 |
|
| 439 |
<p>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.</p> |
| 440 |
|
| 441 |
<H4> <A href="#s6.5.1" id="s6.5.1"> 6.5.1. macOS app bundle </A> </H4> |
| 442 |
|
| 443 |
<p>Directory pure-data/mac contains support files for building a Pure Data macOS application |
| 444 |
bundle and supplementary build scripts for compiling Pd on Macintosh systems, as it is built |
| 445 |
for the ‘vanilla’ releases on msp.ucsd.edu.</p> |
| 446 |
|
| 447 |
<p>In a nutshell, a monolithic macOS “application” is simply a directory structure |
| 448 |
treated as a single object by the OS. Inside this bundle are the compiled binaries, resource |
| 449 |
files, and contextual information. You can look inside any application by either navigating |
| 450 |
inside it from the commandline or by right-clicking on it in Finder and choosing “Show |
| 451 |
Package Contents.”</p> |
| 452 |
|
| 453 |
<p>The basic layout is:</p> |
| 454 |
|
| 455 |
<pre><code>Pd-0.55-0.app/Contents |
| 456 |
Info.plist <- contextual info: version string, get info string, etc |
| 457 |
/Frameworks <- embedded Tcl/Tk frameworks (optional) |
| 458 |
/MacOS/Pd <- renamed Wish bundle launcher |
| 459 |
/Resources |
| 460 |
/bin <- pd binaries |
| 461 |
/doc <- built in docs & help files |
| 462 |
/extra <- core externals |
| 463 |
/font <- included fonts |
| 464 |
/po <- text translation files |
| 465 |
/src <- Pd source header files |
| 466 |
/tcl <- Pd GUI scripts |
| 467 |
</code></pre> |
| 468 |
|
| 469 |
<p>The Pure Data GUI utilizes the Tk windowing shell aka “Wish” at runtime. |
| 470 |
Creating a Pure Data .app involves using a precompiled Wish.app as a wrapper |
| 471 |
by copying the Pd binaries and resources inside of it.</p> |
| 472 |
|
| 473 |
<H5> <A href="#s6.5.1.1" id="s6.5.1.1"> 6.5.1.1. macOS App bundle helpers </A> </H5> |
| 474 |
|
| 475 |
<ul> |
| 476 |
<li>osx-app.sh: creates a Pd .app bundle for macOS using a Tk Wish.app wrapper</li> |
| 477 |
<li>tcltk-wish.sh: downloads and builds a Tcl/Tk Wish.app for macOS</li> |
| 478 |
</ul> |
| 479 |
|
| 480 |
<p>These scripts complement the autotools build system described in INSTALL.txt and |
| 481 |
are meant to be run after Pd is configured and built. The following usage, for |
| 482 |
example, downloads and builds a 32 bit Tk 8.6.6 Wish.app which is used to create |
| 483 |
a macOS Pd-0.55-0.app:</p> |
| 484 |
|
| 485 |
<pre><code>mac/tcltk-wish.sh --arch i386 8.6.6 |
| 486 |
mac/osx-app.sh --wish Wish-8.6.6.app 0.55-0 |
| 487 |
</code></pre> |
| 488 |
|
| 489 |
<p>Both osx-app.sh & tcltck-wish.sh have extensive help output using the <code>--help</code> |
| 490 |
commandline option:</p> |
| 491 |
|
| 492 |
<pre><code>mac/osx-app.sh --help |
| 493 |
mac/tcltk-wish.sh --help |
| 494 |
</code></pre> |
| 495 |
|
| 496 |
<p>The osx-app.sh script automates building the Pd .app bundle and is used in the |
| 497 |
<code>make app</code> makefile target. This default action can be invoked manually after |
| 498 |
Pd is built:</p> |
| 499 |
|
| 500 |
<pre><code>mac/osx-app.sh 0.55-0 |
| 501 |
</code></pre> |
| 502 |
|
| 503 |
<p>This builds a <code>Pd-0.55-0.app</code> using the included Wish. If you omit the version |
| 504 |
argument, a <code>Pd.app</code> is built. The version argument is only used as a suffix to |
| 505 |
the file name and contextual version info is pulled from configure script |
| 506 |
output.</p> |
| 507 |
|
| 508 |
<p>A pre-built universal (32/64 bit) Tk 8.6.10+ Wish with patches applied is |
| 509 |
included with the Pd source distribution and works across the majority of macOS |
| 510 |
versions up to 10.15. This is the default Wish.app when using <code>osx-app.sh</code>. If you |
| 511 |
want to use a different Wish.app (a newer version, a custom build, a system |
| 512 |
version), you can specify the donor via commandline options, for example:</p> |
| 513 |
|
| 514 |
<pre><code># build Pd-0.55-0.app using Tk 8.6 installed to the system |
| 515 |
mac/osx-app.sh --system-tk 8.6 0.55-0 |
| 516 |
</code></pre> |
| 517 |
|
| 518 |
<p>If you want Pd to use a newer version of Tcl/Tk, but do not want to install to |
| 519 |
it to your system, you can build Tcl/Tk as embedded frameworks inside of the Pd |
| 520 |
.app bundle. This has the advantage of portability to other systems.</p> |
| 521 |
|
| 522 |
<p>The tcltk-wish.sh script automates building a Wish.app with embedded Tcl/Tk, |
| 523 |
either from the release distributions or from a git clone:</p> |
| 524 |
|
| 525 |
<pre><code># build Wish-8.6.6.app with embedded Tcl/Tk 8.6.6 |
| 526 |
mac/tcltk-wish.sh 8.6.6 |
| 527 |
|
| 528 |
# build Wish-master-git.app from the latest Tcl/Tk master branch from git |
| 529 |
mac/tcltk-wish.sh --git master-git |
| 530 |
</code></pre> |
| 531 |
|
| 532 |
<p>You can also specify which architectures to build (32 bit, 64 bit, or both):</p> |
| 533 |
|
| 534 |
<pre><code># build 32 bit Wish-8.6.6.app with embedded Tcl/Tk 8.6.6 |
| 535 |
mac/tcltk-wish.sh --arch i386 8.6.6 |
| 536 |
|
| 537 |
# build universal (32 & 64 bit) |
| 538 |
mac/tcltk-wish.sh --universal 8.6.6 |
| 539 |
</code></pre> |
| 540 |
|
| 541 |
<p>Once your custom Wish.app is built, you can use it as the .app source for |
| 542 |
osx-app.sh with the -w/–wish option:</p> |
| 543 |
|
| 544 |
<pre><code># build Pd with a custom Tcl/Tk 8.6.6 Wish |
| 545 |
mac/osx-app.sh -w Wish-8.6.6.app |
| 546 |
</code></pre> |
| 547 |
|
| 548 |
<p>Downloading and building Tcl/Tk takes some time. If you are doing lots of builds |
| 549 |
of Pd and/or are experimenting with different versions of Tcl/Tk, building the |
| 550 |
embedded Wish.apps you need with tcltk-wish.sh can save you some time as they |
| 551 |
can be reused when (re)making the Pd .app bundle.</p> |
| 552 |
|
| 553 |
<p>Usually, it’s best to use stable releases of Tcl/Tk. However, there are times |
| 554 |
when building from the current development version is useful. For instance, |
| 555 |
if there is a bug in the Tcl/Tk sources and the generated Wish.app crashes on |
| 556 |
your system, you can then see if there is a fix for this in the Tcl/Tk |
| 557 |
development version on GitHub. If so, then you can test by using the |
| 558 |
tcltk-wish.sh <code>--git</code> commandline option. Oftentimes, these kinds of issues will |
| 559 |
appear with a newer version of macOS before they have been fixed by the open |
| 560 |
source community.</p> |
| 561 |
|
| 562 |
<p>Additionally, Pd uses an older version of Tcl/Tk for backwards compatibility on |
| 563 |
macOS. As such, small bugfixes from newer versions may need to be backported for |
| 564 |
the Pd GUI. Currently, this is handled in the tcltk-wish.sh script by applying |
| 565 |
custom patches to either the Tcl and/or Tk source trees. To skip applying |
| 566 |
patches, use the tcltk-wish.sh <code>--no-patches</code> commandline option. See |
| 567 |
<code>mac/patches/README.txt</code> for more info.</p> |
| 568 |
|
| 569 |
<H4> <A href="#s6.5.2" id="s6.5.2"> 6.5.2. Supplementary macOS build scripts </A> </H4> |
| 570 |
|
| 571 |
<ul> |
| 572 |
<li>build-macosx: builds a 32 bit Pd .app bundle using src/makefile.mac</li> |
| 573 |
<li>build-mac64: builds a 64 bit Pd .app bundle using src/makefile.mac</li> |
| 574 |
</ul> |
| 575 |
|
| 576 |
|
| 577 |
<p>These scripts automate building Pd with the fallback makefiles in the src |
| 578 |
directory.</p> |
| 579 |
|
| 580 |
<p>To build a 32 bit Pd, copy this “mac” directory |
| 581 |
somewhere like <code>~/mac</code>. Also copy a source tarball there, such as |
| 582 |
pd-0.55-0.src.tar.gz. Then cd to <code>~/mac</code> and type:</p> |
| 583 |
|
| 584 |
<pre><code>./build-macosx 0.55-0 |
| 585 |
</code></pre> |
| 586 |
|
| 587 |
<p>If all goes well, you’ll soon see a new app appear named Pd-0.55-0.app.</p> |
| 588 |
|
| 589 |
<p>If you want to build a 64 bit Pd, perform the same steps and use the build-mac64 |
| 590 |
script:</p> |
| 591 |
|
| 592 |
<pre><code>./build-mac64 0.55-0 |
| 593 |
</code></pre> |
| 594 |
|
| 595 |
<p>Note: The “wish-shell.tgz” is an archive of this app I found on my mac: |
| 596 |
<code>/System/Library/Frameworks/Tk.framework/Versions/8.4/Resources/Wish Shell.app</code></p> |
| 597 |
|
| 598 |
<p>A smarter version of the scripts ought to be able to find that file |
| 599 |
automatically on your system so I wouldn’t have to include it here.</p> |
| 600 |
|
| 601 |
<H4> <A href="#s6.5.3" id="s6.5.3"> 6.5.3. Preferences </A> </H4> |
| 602 |
|
| 603 |
<p>The Pure Data preferences are saved in the macOS “defaults” preference system |
| 604 |
using the following domains:</p> |
| 605 |
|
| 606 |
<ul> |
| 607 |
<li><code>org.puredata.pd</code>: core settings (audio devices, search paths, etc)</li> |
| 608 |
<li><code>org.puredata.pd.pd-gui</code>: GUI settings (recent files, last opened location, etc)</li> |
| 609 |
</ul> |
| 610 |
|
| 611 |
<p>The files themselves live in your user home folder and use the .plist extension:</p> |
| 612 |
|
| 613 |
<pre><code>~/Library/Preferences/org.puredata.pd.plist |
| 614 |
~/Library/Preferences/org.puredata.pd.pd-gui.plist |
| 615 |
</code></pre> |
| 616 |
|
| 617 |
<p>These files use the Apple Property List XML format and shouldn’t be edited |
| 618 |
directly. You can look inside, edit, and/or delete these using the <code>defaults</code> |
| 619 |
commandline utility in Terminal:</p> |
| 620 |
|
| 621 |
<pre><code># print the contents of the core settings |
| 622 |
defaults read org.puredata.pd |
| 623 |
|
| 624 |
# delete the current GUI settings |
| 625 |
defaults delete org.puredata.pd.pd-gui |
| 626 |
|
| 627 |
# set the startup flag in the core settings |
| 628 |
defaults write org.puredata.pd -array-add flags '-lib Gem' |
| 629 |
</code></pre> |
| 630 |
|
| 631 |
<p>Some important per-application settings required by the GUI include:</p> |
| 632 |
|
| 633 |
<ul> |
| 634 |
<li><code>NSRecentDocuments</code>: string array, list of recently opened files</li> |
| 635 |
<li><code>NSQuitAlwaysKeepsWindows</code>: false, disables default 10.7+ window state saving</li> |
| 636 |
<li><code>ApplePressAndHoldEnabled</code>: false, disables character compose popup, |
| 637 |
enables key repeat for all keys</li> |
| 638 |
<li><code>NSRequiresAquaSystemAppearance</code>: true, disables dark mode for Pd GUI on 10.14+</li> |
| 639 |
</ul> |
| 640 |
|
| 641 |
<p>These are set in:</p> |
| 642 |
<pre><code>tcl/pd_guiprefs.tcl</code></pre> |
| 643 |
|
| 644 |
<H4> <A href="#s6.5.4" id="s6.5.4"> 6.5.4. Code signing </A> </H4> |
| 645 |
|
| 646 |
<p>As of Pd 0.51, the mac/osx-app.sh script performs “ad-hoc code signing” in order |
| 647 |
to set entitlements to open un-validated dynamic libraries on macOS 10.15+. This |
| 648 |
is required due to the new security settings. Note: ad-hoc signing doesn’t |
| 649 |
actually sign the .app bundle with an account certificate, so the unidentified |
| 650 |
developer warning is still shown when the downloaded .app is run for the first |
| 651 |
time.</p> |
| 652 |
|
| 653 |
<H4> <A href="#s6.5.5" id="s6.5.5"> 6.5.5. Privacy permission </A> </H4> |
| 654 |
|
| 655 |
<p>The macOS 10.14 release introduced system privacy permissions for actions |
| 656 |
applications can undertake on a user account, such as accessing files or reading |
| 657 |
microphone or camera input. When an application is started for the first time |
| 658 |
and tries to access something that is covered by the privacy settings, a |
| 659 |
permissions prompt is displayed by the system requesting access. The action is |
| 660 |
then allowed or denied and this setting is saved and applied when the |
| 661 |
application is run again in the future.</p> |
| 662 |
|
| 663 |
<p>As of macOS 10.15, running Pd will request access for the following:</p> |
| 664 |
|
| 665 |
<ul> |
| 666 |
<li>Files and Folders: Documents</li> |
| 667 |
<li>Files and Folders: Desktop</li> |
| 668 |
<li>Microphone</li> |
| 669 |
</ul> |
| 670 |
|
| 671 |
<p>Additionally, using an external such as Gem for camera input will request |
| 672 |
access to the Camera.</p> |
| 673 |
|
| 674 |
<p>The current permissions can be changed in Privacy panel in System Preferences. |
| 675 |
They can also be reset on the commandline using the <code>tccutil</code> command and the |
| 676 |
Pd .app bundle id:</p> |
| 677 |
|
| 678 |
<pre><code># reset Pd's Microphone privacy setting |
| 679 |
tccutil reset Microphone org.puredata.pd.pd-gui |
| 680 |
|
| 681 |
# reset all of Pd's privacy settings |
| 682 |
tccutil reset All org.puredata.pd.pd-gui |
| 683 |
</code></pre> |
| 684 |
|
| 685 |
<H4> <A href="#s6.5.6" id="s6.5.6"> 6.5.6. Font issues with macOS 10.15+ </A> </H4> |
| 686 |
|
| 687 |
<p>macOS 10.15 added further changes to font rendering beginning with 10.14, with |
| 688 |
the weird result that Pd’s default font, DejaVu Sans Mono, renders thinner and |
| 689 |
with narrower letter spacing than system fonts. This results in objects on the patch |
| 690 |
canvas being wider than their inner text and text selection positioning being off.</p> |
| 691 |
|
| 692 |
<p>To remedy this for now, Pd 0.51-3 changed Pd’s default font for macOS to Menlo |
| 693 |
which is included with the system since 10.6. Menlo is based on Bitstream Vera |
| 694 |
Mono and DejaVu Sans Mono, so there should be no issues with patch sizing or |
| 695 |
positioning.</p> |
| 696 |
|
| 697 |
<H4> <A href="#s6.5.7" id="s6.5.7"> 6.5.7. Dark mode </A> </H4> |
| 698 |
|
| 699 |
<p>Pd currently disables Dark Mode support by setting the |
| 700 |
NSRequiresAquaSystemAppearance key to true in both the app bundle’s Info.plist |
| 701 |
and the GUI defaults preference file. This restriction may be removed in the |
| 702 |
future once Dark Mode is handled in the GUI.</p> |
| 703 |
|
| 704 |
<H4> <A href="#s6.5.8" id="s6.5.8"> 6.5.8. Debugging releases </A> </H4> |
| 705 |
|
| 706 |
<p>On macOS 10.15+, apps must be signed with an entitlement to allow debugging. |
| 707 |
This is good for security, but bad if you want to run Pd in lldb to figure out |
| 708 |
why your custom external is crashing.</p> |
| 709 |
|
| 710 |
<p>To make this work, the entitlement can be added to an existing Pd release .app |
| 711 |
bundle using the <code>codesign</code> command in Terminal (steps by Pierre Alexandre |
| 712 |
Tremblay):</p> |
| 713 |
|
| 714 |
<ul> |
| 715 |
<li>Extract the current Pd entitlements from the internal pd binary:</li> |
| 716 |
</ul> |
| 717 |
|
| 718 |
|
| 719 |
<pre><code> codesign -d /Applications/Pd-0.53-2.app/Contents/Resources/bin/pd \ |
| 720 |
--entitlements :~/Desktop/pd-entitlements.xml |
| 721 |
</code></pre> |
| 722 |
|
| 723 |
<ul> |
| 724 |
<li>Edit pd-entitlements.xml on your Desktop, add the following key, and save:</li> |
| 725 |
</ul> |
| 726 |
|
| 727 |
|
| 728 |
<pre><code> <key>com.apple.security.get-task-allow</key> |
| 729 |
<true/> |
| 730 |
</code></pre> |
| 731 |
|
| 732 |
<ul> |
| 733 |
<li>Re-sign the pd binary with the updated entitlements:</li> |
| 734 |
</ul> |
| 735 |
|
| 736 |
|
| 737 |
<pre><code> codesign -s - --deep --force --options=runtime \ |
| 738 |
--entitlements ~/Desktop/pd-entitlements.xml \ |
| 739 |
/Applications/Pd-0.53-2.app/Contents/Resources/bin/pd |
| 740 |
</code></pre> |
| 741 |
|
| 742 |
<p>Now Pd can be run with lldb using:</p> |
| 743 |
|
| 744 |
<pre><code>lldb /Applications/Pd-0.53-2.app/Contents/Resources/bin/pd |
| 745 |
</code></pre> |
| 746 |
|
| 747 |
<p>Note: Re-signing using an ad-hoc identifier will work on the development system, |
| 748 |
but running the Pd .app bundle on another system will result in security |
| 749 |
warnings as the original signature and notarization are invalid.</p> |
| 750 |
|
| 751 |
|
| 752 |
<H3> <A href="#s6.6" id="s6.6"> 6.6. Building Pd for Microsoft Windows </A> </H3> |
| 753 |
|
| 754 |
<p>Pd on Windows can be built with either MinGW or Cygwin which provide the core build requirements: a compiler chain & shell environment.</p> |
| 755 |
<p>It is recommended to use the Msys2 distribution which provides both a Unix command shell and MinGW. Download the Msys2 "x86_64" 64 bit installer (or "i686" if you are using 32 bit Windows) from:</p> |
| 756 |
|
| 757 |
<p><a href="http://www.msys2.org/" target="_blank">http://www.msys2.org/</a></p> |
| 758 |
|
| 759 |
<p>Then install to the default location (<code>C:\msys32</code> or <code>C:\msys64</code>) and follow the setup/update info on the Msys2 webpage.</p> |
| 760 |
<p>Msys2 provides both 32 and 64 MinGW and command shells. As of Pd 0.50, the Pd release is 64 bit for Windows, so it is recommended to set up and use the MinGW 64 bit shell. If you want to build a 32 bit Pd, similarly use the MinGW 32 bit shell. Due to how MinGW is designed, you cannot build a 64 bit Pd with a 32 bit MinGW and vice versa. This also means the Pd configure <code>--enable-universal</code> build option has no effect in MinGW.</p> |
| 761 |
<p>Note: Msys2 development seems to change frequently, so some of the package names below may have changed after this document was written.</p> |
| 762 |
<p>Open an Msys2 shell and install the compiler chain, autotools, & gettext via:</p> |
| 763 |
|
| 764 |
|
| 765 |
<pre><code> |
| 766 |
# The MINGW_PACKAGE_PREFIX variable is automatically set by MinGW |
| 767 |
# On MinGW64, it is MINGW_PACKAGE_PREFIX=mingw-w64-x86_64 |
| 768 |
# On MinGW32, it is MINGW_PACKAGE_PREFIX=mingw-w64-i686 |
| 769 |
pacman -S make autoconf automake libtool \ |
| 770 |
${MINGW_PACKAGE_PREFIX}-toolchain ${MINGW_PACKAGE_PREFIX}-clang \ |
| 771 |
${MINGW_PACKAGE_PREFIX}-gettext |
| 772 |
</code></pre> |
| 773 |
|
| 774 |
<p>Install git if you want to clone the Pd sources from Github, etc:</p> |
| 775 |
|
| 776 |
<pre><code>pacman -S git</code></pre> |
| 777 |
|
| 778 |
<p>and/or the nsis installer tool if you want to build the Pd Windows installer:</p> |
| 779 |
|
| 780 |
<pre><code># 64 bit |
| 781 |
pacman -S mingw-w64-x86_64-nsis |
| 782 |
|
| 783 |
# 32 bit |
| 784 |
pacman -S mingw-w64-i686-nsis</code></pre> |
| 785 |
|
| 786 |
<p>Note: You can also search for packages in Msys2 with:</p> |
| 787 |
|
| 788 |
<pre><code>pacman -S -s <searchterm></code></pre> |
| 789 |
|
| 790 |
<p>Once the packages are installed, you should now be ready to build Pd by following the general autotools build steps.</p> |
| 791 |
<p>The following audio APIs are available on Windows and can be enabled/disabled via their configure flags:</p> |
| 792 |
|
| 793 |
<ul> |
| 794 |
<li>MMIO: <code>--enable-mmio</code> or <code>--disable-mmio</code> (default enabled)</li> |
| 795 |
<li>ASIO: <code>--enable-asio</code> or <code>--disable-asio</code> (default enabled, if found)</li> |
| 796 |
<li>JACK: <code>--enable-jack</code> or <code>--disable-jack</code></li> |
| 797 |
</ul> |
| 798 |
|
| 799 |
<p>For example, to build Pd without MMIO support:</p> |
| 800 |
|
| 801 |
<pre><code>./configure --disable-mmio</code></pre> |
| 802 |
|
| 803 |
<p>Note: Because of license restrictions, Pd cannot distribute the ASIO SDK source files. If you want to build Pd with ASIO support, see <a href="6.building.from.source.htm#s6.6.4">6.6.4 Windows ASIO support </a> for further instructions.</p> |
| 804 |
<p>Once built Pd is built, you can either:</p> |
| 805 |
|
| 806 |
<ul> |
| 807 |
<li>build a Pd application directory for Windows (recommended)</li> |
| 808 |
<li>build a Windows installer</li> |
| 809 |
</ul> |
| 810 |
|
| 811 |
<p>A Pd application directory is essentially a self-contained Pd package which should run out of the box. To build, simply use:</p> |
| 812 |
|
| 813 |
<pre><code>make app</code></pre> |
| 814 |
|
| 815 |
<p>This will create a "pd-VERSION" directory (ie. pd-0.48.1) which can then be used by running pd.exe in the bin directory and placed wherever on your system. More info & options regarding the Pd app directory is provided next </p> |
| 816 |
|
| 817 |
<p>To build a .msi Windows installer for Pd, see msw/build-nsi.sh.</p> |
| 818 |
|
| 819 |
<p>Note: The standard <code>make install</code> requires Tcl/Tk and won't work |
| 820 |
outside your Cygwin/Msys2 environment (if at all).</p> |
| 821 |
|
| 822 |
<H4> <A href="#s6.6.1" id="s6.6.1"> 6.6.1. Building a Pd application </A> </H4> |
| 823 |
|
| 824 |
<p>Directory pure-data/msw contains support files for building a Pure Data Windows |
| 825 |
application, as it is built for the ‘vanilla’ releases on msp.ucsd.edu.</p> |
| 826 |
|
| 827 |
<p>As of Pd version 0.50, all releases are compiled using Dan Wilcox’s scripts, |
| 828 |
<code>msw-app.sh</code>, and optionally <code>tcltk-dir.sh</code> (which builds a version of TCL/TK in |
| 829 |
case you don’t already have one).</p> |
| 830 |
|
| 831 |
<p>The Pd sources aren’t completely self-contained: Because of licensing |
| 832 |
restrictions, the ASIO support files are not included in the Pd source tree. |
| 833 |
The <code>msw-app.sh</code> script presumes you’ve downloaded the ASIO SDK and can point |
| 834 |
<code>msw-app.sh</code> to it.</p> |
| 835 |
|
| 836 |
<p>It’s also possible to compile Pd using Visual C. This is not managed |
| 837 |
automatically but you can look in <code>how-to-use-msvc.sh</code>; to see how it can be |
| 838 |
done. This compiler gives different warnings which are sometimes useful, and |
| 839 |
refuses to compile code that has variable declarations in the middle of a |
| 840 |
block. It’s a good idea to test pull requests against MSVC if you can. The |
| 841 |
file <code>pdprototype.zip</code> contains all the garbage that Pd needs in addition to its |
| 842 |
own files, including tcl/tk. MSVC compilation works in 32 bits only.</p> |
| 843 |
|
| 844 |
<p>The scripts <code>build-msw-32.sh</code> and <code>build-msw-64.sh</code> are the ones used by Miller to |
| 845 |
make Pd releases. These files work on Linux only and will not work out of |
| 846 |
the box unless your file tree resembles Miller’s in some ways (pd source is in |
| 847 |
<code>~/pd</code> for instance) but you can presumably make your own version if you need to.</p> |
| 848 |
|
| 849 |
<p>But to first get things working, it’s best to use <code>msw-app.sh</code> and <code>tcltk-dir.sh</code> |
| 850 |
directly.</p> |
| 851 |
|
| 852 |
<H4> <A href="#s6.6.2" id="s6.6.2"> 6.6.2. Pd application directory </A> </H4> |
| 853 |
|
| 854 |
<p>Pd for Windows is essentially a stand-alone application directory which contains |
| 855 |
the compiled binaries, resource files, and contextual information.</p> |
| 856 |
|
| 857 |
<p>The basic layout is:</p> |
| 858 |
|
| 859 |
<pre>pd |
| 860 |
/bin <- pd binaries |
| 861 |
/doc <- built in docs & help files |
| 862 |
/extra <- core externals |
| 863 |
/font <- included fonts |
| 864 |
/lib <- embedded Tcl/Tk frameworks |
| 865 |
/po <- text translation files |
| 866 |
/src <- Pd source header files |
| 867 |
/tcl <- Pd GUI scripts</pre> |
| 868 |
|
| 869 |
<p>The Pure Data GUI utilizes the Tk windowing shell aka “wish##.exe” at runtime |
| 870 |
which is included with Pd in the <code>/bin</code> directory. A Pure Data app directory |
| 871 |
includes both the Pd binaries and resources as well as a precompiled Tk.</p> |
| 872 |
|
| 873 |
<H5> <A href="#s6.6.2.1" id="s6.6.2.1"> 6.6.2.1. Windows app bundle helpers </A> </H5> |
| 874 |
|
| 875 |
<ul> |
| 876 |
<li><code>msw-app.sh</code>: creates a Pd app directory for Windows using precompiled Tcl/Tk</li> |
| 877 |
<li><code>tcltk-dir.sh</code>: downloads and builds Tcl/Tk for Windows</li> |
| 878 |
</ul> |
| 879 |
|
| 880 |
<p>These scripts complement the autotools build system described in INSTALL.txt and |
| 881 |
are meant to be run after Pd is configured and built. The following usage, for |
| 882 |
example, downloads and builds 32 bit Tk 8.6.8 which is used to create |
| 883 |
a Windows pd-0.48-1 directory:</p> |
| 884 |
|
| 885 |
<pre><code>msw/tcltk-dir.sh 8.6.8 |
| 886 |
msw/msw-app.sh --tk tcltk-8.6.8 0.48-1 |
| 887 |
</code></pre> |
| 888 |
|
| 889 |
<p>Both <code>msw-app.sh</code> & <code>tcltck-dir.sh</code> have extensive help output using the <code>--help</code> |
| 890 |
commandline option:</p> |
| 891 |
|
| 892 |
<pre><code>msw/msw-app.sh --help |
| 893 |
msw/tcltk-dir.sh --help |
| 894 |
</code></pre> |
| 895 |
|
| 896 |
<p>The <code>msw-app.sh</code> script automates building the Pd app directory and is used in the |
| 897 |
<code>make app</code> makefile target. This default action can be invoked manually after |
| 898 |
Pd is built:</p> |
| 899 |
|
| 900 |
<pre><code>msw/msw-app.sh 0.55-0 |
| 901 |
</code></pre> |
| 902 |
|
| 903 |
<p>This builds a “pd-0.55-0” directory using the default copy of Tk. If you omit |
| 904 |
the version argument, a “pd” directory is built. The version argument is only |
| 905 |
used as a suffix to the directory name.</p> |
| 906 |
|
| 907 |
<p>The <code>msw/pdprototype.tgz</code> archive contains the basic requirements for running Pd |
| 908 |
on Windows: a precompiled copy of Tcl/Tk and various .dll library files. This is |
| 909 |
the default Tcl/Tk when using msw-app.</p> |
| 910 |
|
| 911 |
<p>If you want to use a newer Tcl/Tk version or a custom build, you can specify the |
| 912 |
version or directory via commandline options, for example:</p> |
| 913 |
|
| 914 |
<pre><code># create pd-0.48-1 directory, download and build Tcl/Tk 8.5.19 |
| 915 |
msw/msw-app.sh --tk 8.5.19 0.48-1 |
| 916 |
|
| 917 |
# create pd-0.48-1 directory, use Tcl/Tk 8.5.19 built with tcltk-dir.sh |
| 918 |
msw/msw-app.sh --tk tcltk-8.5.19 0.48-1 |
| 919 |
</code></pre> |
| 920 |
|
| 921 |
<p>Note: Depending on which version of Tcl/Tk you want to use, you may need to set |
| 922 |
the Tk Wish command when configuring Pd. To build Pd to use Tk 8.6:</p> |
| 923 |
|
| 924 |
<pre><code>./configure --with-wish=wish86.exe |
| 925 |
make |
| 926 |
</code></pre> |
| 927 |
|
| 928 |
<p>The tcltk-dir.sh script automates building Tcl/Tk for Windows, either from the |
| 929 |
release distributions or from a git clone:</p> |
| 930 |
|
| 931 |
<pre><code># build tcltk-8.5.19 directory with Tcl/Tk 8.5.19 |
| 932 |
msw/tcltk-dir.sh 8.5.19 |
| 933 |
|
| 934 |
# build tcltk-master-git with the latest master branch from git |
| 935 |
msw/tcltk-dir.sh --git master-git |
| 936 |
</code></pre> |
| 937 |
|
| 938 |
<p>Once your custom Tcl/Tk is built, you can use it as the Tk directory source for |
| 939 |
msw-app.sh with the -t/–tk option:</p> |
| 940 |
|
| 941 |
<pre><code># build Pd with a custom Tcl/Tk 8.6.8 directory |
| 942 |
msw/msw-app.sh -t tcltk-8.6.8 |
| 943 |
</code></pre> |
| 944 |
|
| 945 |
<p>Downloading and building Tcl/Tk takes some time. If you are doing lots of builds |
| 946 |
of Pd and/or are experimenting with different versions of Tcl/Tk, building the |
| 947 |
tcltk directories you need with tcltk-dir.sh can save you some time as they |
| 948 |
can be reused when (re)making the Pd app directory.</p> |
| 949 |
|
| 950 |
<p>Usually, it’s best to use stable releases of Tcl/Tk. However, there are times |
| 951 |
when building from the current development version is useful. For instance, |
| 952 |
if there is a bug in the Tcl/Tk sources, you can then see if there is a fix for |
| 953 |
this in the Tcl/Tk development version on GitHub. If so, then you can test by |
| 954 |
using the tcltk-dir.sh <code>--git</code> commandline option.</p> |
| 955 |
|
| 956 |
<p>The tcltk-dir.sh script tries to detect if it’s building in a 64 bit |
| 957 |
environment, ie. MinGW 64. If this detection fails, you can force 64 bit with |
| 958 |
the <code>--64bit</code> option:</p> |
| 959 |
|
| 960 |
<pre><code># force 64 bit Tcl/Tk 8.6.8 build |
| 961 |
tcltk-dir.sh --64bit 8.6.8 |
| 962 |
</code></pre> |
| 963 |
|
| 964 |
<H4> <A href="#s6.6.3" id="s6.6.3"> 6.6.3. pdfontloader </A> </H4> |
| 965 |
|
| 966 |
<p>Tk cannot load local font files by default on Windows. Pd accomplishes this |
| 967 |
through a tiny, custom Tcl extension, pdfontloader.dll. On initialization, the |
| 968 |
Pd GUI tries to load pdfontloader and, if successful, tries to load the included |
| 969 |
Pd font.</p> |
| 970 |
|
| 971 |
<p>Currently, pdfontloader.dll is pre-built and included within the pdprototype.tgz |
| 972 |
tarball. To build pdfontloader, see <a href="https://github.com/pure-data/pdfontloader" target="_blank">https://github.com/pure-data/pdfontloader</a> |
| 973 |
source.</p> |
| 974 |
|
| 975 |
<H4> <A href="#s6.6.4" id="s6.6.4"> 6.6.4. ASIO support </A> </H4> |
| 976 |
|
| 977 |
<p>In order to build ASIO support into Pd on Windows, you need to download the |
| 978 |
ASIO sources from Steinberg directly. Their license does not let us |
| 979 |
redistribute their source files.</p> |
| 980 |
|
| 981 |
<p>Install the ASIO SDK by doing the following:</p> |
| 982 |
|
| 983 |
<ul> |
| 984 |
<li>1. Download the ASIO SDK: <a href="https://www.steinberg.net/en/company/developer.html" target="_blank">https://www.steinberg.net/en/company/developer.html</a></li> |
| 985 |
<li>2. Uncompress asiosdk2.3.zip (or higher) into pure-data/asio/</li> |
| 986 |
<li>3. remove the version number so that you get pure-data/asio/ASIOSDK</li> |
| 987 |
</ul> |
| 988 |
|
| 989 |
<p>Now build Pd and it should include ASIO as one of the audio backends.</p> |
| 990 |
|
| 991 |
<H3> <A href="#s6.7" id="s6.7"> 6.7. Cross-compilation for Windows on Linux </A> </H3> |
| 992 |
|
| 993 |
<p>You can also build a Windows binary of Pd on a Linux system, using a cross-compilation toolchain.</p> |
| 994 |
<p>For Debian based systems (e.g. Ubuntu), you can install the toolchain with:</p> |
| 995 |
|
| 996 |
<pre><code>sudo apt-get install build-essential automake autoconf libtool gettext |
| 997 |
sudo apt-get install mingw-w64 mingw-w64-tools |
| 998 |
sudo apt-get install nsis</code></pre> |
| 999 |
|
| 1000 |
<p>The "mingw-w64" package will install the cross compilation toolchains for both 32bit (<code>g++-mingw-w64-i686</code>, <code>binutils-mingw-w64-i686</code>) and 64bit (<code>g++-mingw-w64-x86-64</code>, <code>binutils-mingw-w64-x86-64</code>).</p> |
| 1001 |
<p>The "nsis" package is purely optional, and only needed if you want to build the installer.</p> |
| 1002 |
<p>You must tell configure that you want to cross-compile for a given architecture via the <code>--host</code> configure flag.</p> |
| 1003 |
<p>For example, to build a 32 bit Pd:</p> |
| 1004 |
|
| 1005 |
<pre><code>./configure --host=i686-w64-mingw32</code></pre> |
| 1006 |
|
| 1007 |
<p>Similarly, to build a 64 bit Pd without ASIO support:</p> |
| 1008 |
|
| 1009 |
<pre><code>./configure --disable-asio --host=x86_64-w64-mingw32</code></pre> |
| 1010 |
|
| 1011 |
<p>If all went well, you should now be ready to build Pd, as explained in the instructions above in the "Windows" section:</p> |
| 1012 |
|
| 1013 |
<pre><code>make app</code></pre> |
| 1014 |
|
| 1015 |
<H3> <A href="#s6.8" id="s6.8"> 6.8. Makefile build </A> </H3> |
| 1016 |
|
| 1017 |
<p>Alternatively, and often more simply, to the autotools build, you can use the fallback makefiles in the src directory:</p> |
| 1018 |
|
| 1019 |
<ul> |
| 1020 |
<li><code>src/makefile.gnu</code>: GNU/Linux</li> |
| 1021 |
<li><code>src/makefile.mac</code>: macOS</li> |
| 1022 |
<li><code>src/makefile.msvc</code>: Windows with Microsoft Visual C</li> |
| 1023 |
<li><code>src/makefile.mingw</code>: Windows with MinGW GCC</li> |
| 1024 |
</ul> |
| 1025 |
|
| 1026 |
<p>On Linux, for example, run the GNU-specific makefile in the src directory:</p> |
| 1027 |
|
| 1028 |
<pre><code>cd src |
| 1029 |
make -f makefile.gnu</code></pre> |
| 1030 |
|
| 1031 |
<p>You can then run directly out of the bin directory without installing:</p> |
| 1032 |
|
| 1033 |
<pre><code>cd ../bin |
| 1034 |
./pd</code></pre> |
| 1035 |
|
| 1036 |
<p>For Microsoft Visual C, first build Pd with the MS VC makefile and then build each external in the extra directory:</p> |
| 1037 |
|
| 1038 |
<pre><code>cd src |
| 1039 |
make -f makefile.msvc |
| 1040 |
cd ../extra/bob~ |
| 1041 |
make pd_nt |
| 1042 |
cd ../bonk~ && make pd_nt |
| 1043 |
cd ../choice && make pd_nt |
| 1044 |
cd ../fiddle~ && make pd_nt |
| 1045 |
...</code></pre> |
| 1046 |
|
| 1047 |
<p>To install Pd to your system on Linux, macOS, & MinGW (Windows), use the <code>install</code> makefile target. For Linux, this is:</p> |
| 1048 |
|
| 1049 |
<pre><code>make -f makefile.gnu install</code></pre> |
| 1050 |
|
| 1051 |
<p>Once installed, you should now be able to run Pd from the commandline:</p> |
| 1052 |
|
| 1053 |
<pre><code>pd</code></pre> |
| 1054 |
|
| 1055 |
<p>If want to uninstall, simply run the <code>uninstall</code> makefile target:</p> |
| 1056 |
|
| 1057 |
<pre><code>make -f makefile.gnu uninstall</code></pre> |
| 1058 |
|
| 1059 |
<p>On macOS, you can build a clickable Pd .app bundle using the supplemental build |
| 1060 |
scripts in the mac directory (see <a href="6.building.from.source.htm#s6.5.1">6.5.1 macOS resources</a> |
| 1061 |
for more info).</p> |
| 1062 |
|
| 1063 |
|
| 1064 |
<H3> <A href="#s6.9" id="s6.9"> 6.9. Troubleshooting </A> </H3> |
| 1065 |
|
| 1066 |
<p>Let us know if you run any issues with building or installing Pd:</p> |
| 1067 |
|
| 1068 |
<ul> |
| 1069 |
<li>send an email to the Pd-List: <a href="https://lists.iem.at/postorius/lists/pd-list.lists.iem.at/" target="_blank">https://lists.iem.at/postorius/lists/pd-list.lists.iem.at/</a></li> |
| 1070 |
<li>open an issue: <a href="https://github.com/pure-data/pure-data/issues" target="_blank">https://github.com/pure-data/pure-data/issues</a></li> |
| 1071 |
<li>post to the Pd forum: <a href="https://forum.pdpatchrepo.info" target="_blank">https://forum.pdpatchrepo.info</a></li> |
| 1072 |
</ul> |
| 1073 |
|
| 1074 |
<p>Please include information involved with your problem such as:</p> |
| 1075 |
|
| 1076 |
<ul> |
| 1077 |
<li>information about your system: OS version, libraries installed, etc</li> |
| 1078 |
<li>configure or make output including error lines</li> |
| 1079 |
<li>steps you took: configuration options, etc</li> |
| 1080 |
</ul> |
| 1081 |
|
| 1082 |
</div> |
| 1083 |
<div class="nav nav-bottom"> |
| 1084 |
<div class="nav-back"><A href="5.current.status.htm">< Chapter 5: Current status</A></div> |
| 1085 |
<div class="nav-home"><A href="index.htm#s6">Table of contents</A></div> |
| 1086 |
<div class="nav-forward"></div> |
| 1087 |
</div> |
| 1088 |
|
| 1089 |
</BODY> |
| 1090 |
</HTML> |