commit
7498f0214f
@ -0,0 +1,19 @@ |
||||
Pd version 0.53.0 |
||||
|
||||
A real-time graphical programming environment for live interactive |
||||
computer music, Pd works on Linux, Apple macOS, and Microsoft Windows. |
||||
|
||||
Pd is copyrighted, but is free for you to use for any reasonable purpose. |
||||
See the file: |
||||
PD_BASEDIR/LICENSE.txt |
||||
|
||||
Reference manual for Pd lives in: |
||||
PD_BASEDIR/doc/1.manual/index.htm |
||||
or online: |
||||
http://msp.ucsd.edu/Pd_documentation/ |
||||
|
||||
Information of all sorts (guides, development, meetings, more documentation, etc): |
||||
http://puredata.info |
||||
|
||||
The Pd mailing list archive lives in: |
||||
https://lists.puredata.info/pipermail/pd-list |
||||
|
After Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 17 KiB |
|
After Width: | Height: | Size: 5.7 KiB |
|
After Width: | Height: | Size: 1.4 KiB |
|
After Width: | Height: | Size: 4.4 KiB |
|
After Width: | Height: | Size: 7.7 KiB |
|
After Width: | Height: | Size: 65 KiB |
|
After Width: | Height: | Size: 31 KiB |
|
After Width: | Height: | Size: 18 KiB |
|
After Width: | Height: | Size: 39 KiB |
|
After Width: | Height: | Size: 1.7 KiB |
|
After Width: | Height: | Size: 3.6 KiB |
|
After Width: | Height: | Size: 3.6 KiB |
|
After Width: | Height: | Size: 2.9 KiB |
|
After Width: | Height: | Size: 3.2 KiB |
|
After Width: | Height: | Size: 2.8 KiB |
|
After Width: | Height: | Size: 3.3 KiB |
|
After Width: | Height: | Size: 4.2 KiB |
|
After Width: | Height: | Size: 1.8 KiB |
|
After Width: | Height: | Size: 7.7 KiB |
|
After Width: | Height: | Size: 49 KiB |
|
After Width: | Height: | Size: 20 KiB |
|
After Width: | Height: | Size: 36 KiB |
|
After Width: | Height: | Size: 42 KiB |
|
After Width: | Height: | Size: 19 KiB |
|
After Width: | Height: | Size: 44 KiB |
|
After Width: | Height: | Size: 1.4 KiB |
|
After Width: | Height: | Size: 4.1 KiB |
|
After Width: | Height: | Size: 17 KiB |
|
After Width: | Height: | Size: 4.8 KiB |
|
After Width: | Height: | Size: 6.0 KiB |
|
After Width: | Height: | Size: 4.9 KiB |
|
After Width: | Height: | Size: 20 KiB |
|
After Width: | Height: | Size: 4.8 KiB |
|
After Width: | Height: | Size: 4.8 KiB |
|
After Width: | Height: | Size: 3.7 KiB |
|
After Width: | Height: | Size: 6.4 KiB |
|
After Width: | Height: | Size: 38 KiB |
|
After Width: | Height: | Size: 49 KiB |
|
After Width: | Height: | Size: 15 KiB |
|
After Width: | Height: | Size: 17 KiB |
|
After Width: | Height: | Size: 38 KiB |
@ -0,0 +1,236 @@ |
||||
<!DOCTYPE html> |
||||
|
||||
<HTML lang="en"> |
||||
<HEAD> |
||||
<meta charset="UTF-8"> |
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
||||
<TITLE>Pd Manual index</TITLE> |
||||
<meta http-equiv="Content-Type" content="text/html"> |
||||
<link rel="stylesheet" type="text/css" href="pdmanual.css" media="screen"> |
||||
<link rel="icon" type="image/png" href="favicon.ico"> |
||||
</HEAD> |
||||
|
||||
|
||||
<BODY> |
||||
|
||||
<div class="butt"> |
||||
|
||||
</div> |
||||
|
||||
<div id=corpus> |
||||
|
||||
<H1>Pd Manual</H1> |
||||
|
||||
<P> |
||||
This is the Manual for Pd, a patchable environment for audio |
||||
analysis, synthesis, and processing, |
||||
with a rich set of multimedia capabilities. The latest version of this page |
||||
can be found at: |
||||
<a href="http://msp.ucsd.edu/software.html"> |
||||
http://msp.ucsd.edu/software.html</A>. |
||||
<OL> |
||||
<LI> <a href="x1.htm" id=s1>introduction </A> |
||||
<OL> |
||||
<LI> <a href="x1.htm#s1">guide to the documentation </A> |
||||
<LI> <a href="x1.htm#s2">other resources </A> |
||||
</OL> |
||||
|
||||
<LI> <A href="x2.htm" id=s2>theory of operation </A> |
||||
<OL> |
||||
<LI> <A href="x2.htm#s1"> overview </A> |
||||
<OL> |
||||
<LI> <A href="x2.htm#s1.1"> main window, canvases, and printout </A> |
||||
<LI> <A href="x2.htm#s1.2"> object boxes </A> |
||||
<LI> <A href="x2.htm#s1.3"> message and GUI boxes </A> |
||||
<LI> <A href="x2.htm#s1.4"> patches and files </A> |
||||
</OL> |
||||
<LI> <A href="x2.htm#s2"> how to edit patches </A> |
||||
<OL> |
||||
<LI> <A href="x2.htm#s2.1"> edit and run mode </A> |
||||
<LI> <A href="x2.htm#s2.2"> creating boxes </A> |
||||
<LI> <A href="x2.htm#s2.3"> the selection </A> |
||||
<LI> <A href="x2.htm#s2.4"> deleting, cutting, and pasting </A> |
||||
<LI> <A href="x2.htm#s2.5"> changing the text </A> |
||||
<LI> <A href="x2.htm#s2.6"> connecting and disconnecting boxes </A> |
||||
<LI> <A href="x2.htm#s2.7"> properties and help </A> |
||||
</OL> |
||||
<LI> <A href="x2.htm#s3"> messages </A> |
||||
<OL> |
||||
<LI> <A href="x2.htm#s3.1"> anatomy of a message </A> |
||||
<LI> <A href="x2.htm#s3.2"> depth first message passing </A> |
||||
<LI> <A href="x2.htm#s3.3"> |
||||
hot and cold inlets and right to left outlet order </A> |
||||
<LI> <A href="x2.htm#s3.4"> message boxes </A> |
||||
</OL> |
||||
<LI> <A href="x2.htm#s4"> audio signals </A> |
||||
<OL> |
||||
<LI> <A href="x2.htm#s4.1"> sample rate and format </A> |
||||
<LI> <A href="x2.htm#s4.2"> tilde objects and audio connections </A> |
||||
<LI> <A href="x2.htm#s4.3"> converting to and from messages </A> |
||||
<LI> <A href="x2.htm#s4.4"> switching and blocking </A> |
||||
<LI> <A href="x2.htm#s4.5"> nonlocal signal connections </A> |
||||
</OL> |
||||
<LI> <A href="x2.htm#s5"> scheduling </A> |
||||
<OL> |
||||
<LI> <A href="x2.htm#s5.1"> audio and messages </A> |
||||
<LI> <A href="x2.htm#s5.2"> computation load </A> |
||||
<LI> <A href="x2.htm#s5.3"> determinism </A> |
||||
</OL> |
||||
<LI> <A href="x2.htm#s6"> semantics </A> |
||||
<OL> |
||||
<LI> <A href="x2.htm#s6.1"> creation of objects </A> |
||||
<LI> <A href="x2.htm#s6.2"> persistence of data </A> |
||||
<LI> <A href="x2.htm#s6.3"> message passing </A> |
||||
<LI> <A href="x2.htm#s6.4"> inlets and lists </A> |
||||
<LI> <A href="x2.htm#s6.5"> dollar signs </A> |
||||
</OL> |
||||
<LI> <A href="x2.htm#s7"> subpatches </A> |
||||
<OL> |
||||
<LI> <A href="x2.htm#s7.1"> abstractions </A> |
||||
<LI> <A href="x2.htm#s7.2"> graph-on-parent subpatches </A> |
||||
</OL> |
||||
<LI> <A href="x2.htm#s8"> numeric arrays </A> |
||||
<LI> <A href="x2.htm#s9"> data structures </A> |
||||
<OL> |
||||
<LI> <A href="x2.htm#s9.1"> traversal </A> |
||||
<LI> <A href="x2.htm#s9.2"> accessing and changing data </A> |
||||
<LI> <A href="x2.htm#s9.3"> editing </A> |
||||
<LI> <A href="x2.htm#s9.4"> limitations </A> |
||||
</OL> |
||||
|
||||
</OL> |
||||
|
||||
<LI> <a href="x3.htm" id=s3> getting Pd to run </A> |
||||
<OL> |
||||
<LI> <a href="x3.htm#s1.0"> audio and MIDI </A> |
||||
<LI> <a href="x3.htm#s1.1">installing Pd in Microsoft Windows </A> |
||||
<LI> <a href="x3.htm#s1.2">installing Pd in Linux </A> |
||||
<LI> <a href="x3.htm#s1.3">installing Pd in MacOS X </A> |
||||
<LI> <a href="x3.htm#s4"> preferences and startup options </A> |
||||
<LI> <a href="x3.htm#s5"> how Pd searches for files </A> |
||||
</OL> |
||||
|
||||
|
||||
|
||||
|
||||
<li> <a href="x4.htm" id=s4> externals </a> |
||||
|
||||
<ol> |
||||
<li><a href="x4.htm#s1"> external objects & libraries</a> |
||||
<ol> |
||||
<li> <a href="x4.htm#s1.1">what are: vanilla objects, internals & externals? </a> |
||||
<li> <a href="x4.htm#s1.2">what are the types of external objects? </a> |
||||
<ol> |
||||
<li> <a href="x4.htm#s1.2.1">compiled objects:</a> |
||||
<li> <a href="x4.htm#s1.2.2">abstractions:</a> |
||||
</ol> |
||||
<li> <a href="x4.htm#s1.3">what are external libraries?</a> |
||||
<li> <a href="x4.htm#s1.4">what are the types of external libraries?</a> |
||||
</ol> |
||||
|
||||
<li> <a href="x4.htm#s2">installing external objects and libraries</a> |
||||
<ol> |
||||
<li> <a href="x4.htm#s2.1">where to include the externals? </a> |
||||
<li> <a href="x4.htm#s2.2">how to download externals from Pd vanilla?</a> |
||||
</ol> |
||||
|
||||
<li> <a href="x4.htm#s3">loading externals</a> |
||||
<ol> |
||||
<li> <a href="x4.htm#s3.1">load using the [declare] object</a> |
||||
<ol> |
||||
<li> <a href="x4.htm#s3.1.1">[declare -path] </a> |
||||
<li> <a href="x4.htm#s3.1.2">[declare -lib] </a> |
||||
</ol> |
||||
<li> <a href="x4.htm#s3.2">load via path and startup</a> |
||||
<ol> |
||||
<li> <a href="x4.htm#s3.2.1">user added path</a> |
||||
<li> <a href="x4.htm#s3.2.2">startup </a> |
||||
</ol> |
||||
<li> <a href="x4.htm#s3.3">load using slash declarations</a> |
||||
</ol> |
||||
<li> <a href="x4.htm#s4">how externs are loaded </a> |
||||
</OL> |
||||
<LI> <a href="x5.htm" id=s5> current status </A> |
||||
<OL> |
||||
<LI> <a href="x5.htm#s1"> release notes </A> |
||||
<LI> <a href="x5.htm#s2"> known bugs </A> |
||||
<LI> <a href="x5.htm#s3"> differences from Max/MSP </A> |
||||
</OL> |
||||
|
||||
<LI> <a href="x6.htm" id=s6> installing from source </A> |
||||
<OL> |
||||
<LI> <a href="x6.htm#s6.1"> requirements </A> |
||||
<LI> <a href="x6.htm#s6.2"> autotools build (recommended) </A> |
||||
<LI> <a href="x6.htm#s6.3"> Linux & BSD</A> |
||||
<LI> <a href="x6.htm#s6.4"> macOS </A> |
||||
<ol> |
||||
<li><a href="x6-a.htm"> macOS resources </a></li> |
||||
</ol> |
||||
<LI> <a href="x6.htm#s6.5"> Windows </A> |
||||
<ol> |
||||
<li><a href="x6-b.htm"> Windows resources </a></li> |
||||
<li><a href="x6-b.htm#s6.5.2"> Windows ASIO support </a></li> |
||||
</ol> |
||||
<LI> <a href="x6.htm#s6.6"> double precision</A> |
||||
<LI> <a href="x6.htm#s6.7"> other flags</A> |
||||
<LI> <a href="x6.htm#s6.8"> cross-compilation for Windows on Linux </A> |
||||
<LI> <a href="x6.htm#s6.9"> makefile build </A> |
||||
<LI> <a href="x6.htm#s6.10"> reporting bugs </A> |
||||
</OL> |
||||
|
||||
</OL> |
||||
|
||||
</br> |
||||
</br> |
||||
|
||||
<!-- |
||||
intro: what Pd is |
||||
guide to the documentation |
||||
other resources |
||||
|
||||
Theory of operation |
||||
main window and canvases |
||||
messages |
||||
signals |
||||
loading, editing, and saving patches |
||||
subpatches |
||||
one-off and abstractions |
||||
blocking for signals |
||||
data |
||||
|
||||
Making Pd work |
||||
how to get and install Pd |
||||
IRIX |
||||
NT |
||||
Linux |
||||
audio |
||||
testing it |
||||
the scheduler advance |
||||
IRIX |
||||
NT |
||||
Linux |
||||
GEM |
||||
getting it |
||||
running it |
||||
running Pd patches |
||||
command line options |
||||
opening & saving files |
||||
editing |
||||
file stuff |
||||
the path |
||||
abstractions |
||||
externs |
||||
the help feature |
||||
Writing Pd objects in C |
||||
release notes |
||||
features |
||||
bugs |
||||
|
||||
|
||||
--> |
||||
</div> |
||||
|
||||
|
||||
</BODY> |
||||
</HTML> |
||||
|
||||
@ -0,0 +1,232 @@ |
||||
|
||||
|
||||
@charset "utf-8"; |
||||
|
||||
|
||||
:root { |
||||
font-weight: 400; |
||||
} |
||||
|
||||
BODY { |
||||
background: #ffffff;; |
||||
color: #000000; |
||||
font-family: Georgia, serif; /*Georgia, serif; */ /*Helevetica, sans-serif;*/ |
||||
font-size: 12.7pt; /* this is because there were many <p> missing. We can change this value to 7pt to easily detect missing <p> */ |
||||
line-height: 1.6; |
||||
|
||||
} |
||||
|
||||
#corpus { |
||||
|
||||
width: 6.5in; |
||||
margin-left: 0.8in; |
||||
} |
||||
|
||||
H1 { |
||||
font-size: 32.7pt; |
||||
text-align: center; |
||||
font-weight: normal; |
||||
|
||||
|
||||
} |
||||
H2 { |
||||
font-size: 22.7pt; |
||||
text-align: center; |
||||
font-weight: normal; |
||||
|
||||
} |
||||
H3 { |
||||
font-size: 14.7pt; |
||||
text-align: left; |
||||
|
||||
} |
||||
H4 { |
||||
font-size: 12.7pt; |
||||
text-align: left; |
||||
|
||||
} |
||||
H5 { |
||||
font-size: 10.7pt; |
||||
text-align: left; |
||||
|
||||
} |
||||
H6 { |
||||
font-size: 10.7pt; |
||||
text-align: left; |
||||
|
||||
} |
||||
|
||||
H1, H2, H3, H4, H5, H6, ol, ul, mark, PRE { |
||||
color: #3E4349; |
||||
|
||||
} |
||||
|
||||
PRE { |
||||
font-size: 80%; |
||||
background-color:#f0f0f0; |
||||
text-align: left; |
||||
border-radius: 8px; |
||||
padding: 8px; |
||||
font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; |
||||
} |
||||
|
||||
table, td, th { |
||||
border: 1px solid black; |
||||
color: #3E4349; |
||||
font-size: 12.7pt; |
||||
padding: 6px; |
||||
} |
||||
|
||||
table { |
||||
border-collapse: collapse; |
||||
} |
||||
|
||||
tr:nth-child(even) {background-color: #f0f0f0;} |
||||
|
||||
CODE { |
||||
background-color:#f0f0f0; |
||||
font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace; |
||||
} |
||||
|
||||
ol { |
||||
font-size: 14.5pt; |
||||
text-align: left; |
||||
line-height: 1.6; |
||||
} |
||||
|
||||
|
||||
P { |
||||
font-size: 12.7pt; |
||||
text-align: left; |
||||
line-height: 1.6; |
||||
color: #3E4349; |
||||
line-height: 1.4em; |
||||
} |
||||
|
||||
ul { |
||||
font-size: 12.7pt; |
||||
text-align: left; |
||||
line-height: 1.6; |
||||
color: #3E4349; |
||||
line-height: 1.4em; |
||||
} |
||||
|
||||
|
||||
/* standard link */ |
||||
|
||||
a:link { |
||||
text-decoration: none; |
||||
color: #006699; |
||||
} |
||||
|
||||
a:visited { |
||||
text-decoration: none; |
||||
color: #006699; |
||||
} |
||||
|
||||
a:hover { |
||||
|
||||
background-color:#eeeee4; |
||||
} |
||||
|
||||
a:active { |
||||
text-decoration: none; |
||||
color: blue; |
||||
} |
||||
|
||||
|
||||
/* green link (like a button) */ |
||||
|
||||
a.green:link { |
||||
font-family:sans-serif; |
||||
background-color: #4CAF50; /* Green */ |
||||
border-radius: 4px; |
||||
color: white; |
||||
padding: 0px 8px ; |
||||
text-align: center; |
||||
text-decoration: none; |
||||
display: inline-block; |
||||
font-size: 80%; |
||||
|
||||
} |
||||
|
||||
a.green:hover { |
||||
text-decoration: none; |
||||
background-color: #4CAF50; |
||||
} |
||||
|
||||
a.green:visited { |
||||
color: white; |
||||
} |
||||
|
||||
|
||||
/* button like a link */ |
||||
|
||||
.btn-toggle-theme, .btn-toggle-font { |
||||
background-color: transparent; |
||||
border: none; |
||||
color: #666666; |
||||
text-align: center; |
||||
text-decoration: none; |
||||
font-size: 16px; |
||||
cursor: pointer; |
||||
} |
||||
|
||||
/* standard images */ |
||||
|
||||
IMG { |
||||
|
||||
display: block; |
||||
margin: 0 auto; |
||||
width: auto; |
||||
filter: brightness(1) contrast(1); |
||||
|
||||
} |
||||
|
||||
mark { |
||||
background-color: #fff0b3; |
||||
} |
||||
|
||||
p.fig { |
||||
text-align: center; |
||||
} |
||||
|
||||
div.butt { |
||||
position: fixed; |
||||
top: 0; |
||||
left: 0; |
||||
} |
||||
|
||||
blockquote { |
||||
padding: 0; |
||||
margin-right:0px; |
||||
} |
||||
|
||||
blockquote p { |
||||
text-align: right; |
||||
} |
||||
|
||||
|
||||
/* responsive css for small "devices" */ |
||||
|
||||
@media screen and (max-device-width: 700px) { |
||||
#corpus { |
||||
padding: 10px; |
||||
width: auto; |
||||
margin-left: 6px; |
||||
} |
||||
H1 {font-size: 25pt;} |
||||
IMG {max-width: 100%;} |
||||
} |
||||
|
||||
/* responsive css for small "browser window" */ |
||||
|
||||
@media screen and (max-width: 700px) { |
||||
#corpus { |
||||
padding: 10px; |
||||
width: auto; |
||||
margin-left: 6px; |
||||
} |
||||
H1 {font-size: 25pt;} |
||||
IMG {max-width: 100%;} |
||||
} |
||||
@ -0,0 +1,144 @@ |
||||
<!DOCTYPE html> |
||||
|
||||
<HTML lang="en"> |
||||
<HEAD> |
||||
<meta charset="UTF-8"> |
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
||||
<TITLE>Pd Manual 1</TITLE> |
||||
<meta http-equiv="Content-Type" content="text/html"> |
||||
<link rel="stylesheet" type="text/css" href="pdmanual.css" media="screen"> |
||||
<link rel="icon" type="image/png" href="favicon.ico"> |
||||
</HEAD> |
||||
|
||||
<BODY> |
||||
|
||||
|
||||
<div class="butt"> |
||||
|
||||
</div> |
||||
|
||||
<div id=corpus> |
||||
|
||||
<H2>Pd Manual chapter 1: introduction</H2> |
||||
|
||||
<P> |
||||
<A href="index.htm#s1"> back to table of contents </A> |
||||
<BR><BR> |
||||
</P> |
||||
|
||||
|
||||
<P> |
||||
This is the HTML documentation for the Pd computer program. |
||||
Pd is free and can be downloaded from the internet; |
||||
go to |
||||
<A href="http://msp.ucsd.edu/software.html"> |
||||
http://msp.ucsd.edu/software.html</A> |
||||
to get it. |
||||
<H3> <A id=s1> 1.1. Guide to Pd's documentation </A> </H3> |
||||
|
||||
<P> Pd's documentation lives in the "doc" folder of the distribution and consists of: |
||||
|
||||
<UL> |
||||
<LI>this HTML manual<br> |
||||
<PRE> |
||||
Pd/ |
||||
├── doc/ |
||||
├── 1.manual/ |
||||
</PRE> |
||||
|
||||
<LI>"reference" (or 'help') patches, for all objects in Pd<br> |
||||
<PRE> |
||||
Pd/ |
||||
├── doc/ |
||||
├── 5.reference/ |
||||
</PRE> |
||||
|
||||
<LI>"example" patches showing how to do things<br> |
||||
|
||||
|
||||
<PRE> |
||||
Pd/ |
||||
├── doc/ |
||||
├── 2.control.examples/ |
||||
├── 3.audio.examples/ |
||||
├── 4.data.structures/ |
||||
</PRE> |
||||
|
||||
<LI>sample C code on how to write externals<br> |
||||
<PRE> |
||||
Pd/ |
||||
├── doc/ |
||||
├── 6.externs/ |
||||
</PRE> |
||||
|
||||
</UL> |
||||
|
||||
<P> |
||||
This Manual has six sections: |
||||
|
||||
<OL> |
||||
<LI> this introduction |
||||
<LI> <A href="x2.htm"> |
||||
a theory of operations, explaining how Pd works </A> |
||||
<LI> <A href="x3.htm"> |
||||
instructions on installing Pd and getting it to run </A> |
||||
<LI> <A href="x4.htm"> externals </A> |
||||
<LI> <A href="x5.htm"> release notes and known bugs </A> |
||||
<LI> <A href="x6.htm"> installing from source </A> |
||||
</OL> |
||||
|
||||
<P> |
||||
For a list of all the objects you can use menu <b>Help/List of objects</b>. To get help on any |
||||
Pd object you can right click on it; or you can browse the help patches |
||||
by choosing menu <b>Help/Browser</b> and looking in |
||||
"Pure Data/5.reference". |
||||
|
||||
<P> |
||||
The "example" patches are also available from Pd's browser. They appear in subdirectories |
||||
named "2.control.examples", "3.audio.examples" and "4.data.structures". Some additional |
||||
patches in "7.stuff" might also be helpful. |
||||
|
||||
<P> |
||||
To get started writing your own C extensions, refer to "6.externs". For more about externals, |
||||
please refer to <A href=x4.htm>chapter 4 </A>of this manual. |
||||
|
||||
<H3> <A id=s2> 1.2. other resources </A> </H3> |
||||
|
||||
<P> There is a very extensive Pd community web site, |
||||
<a href="http://www.pure-data.info/"> pure-data.info</a>, which aims to be the central resource for Pd, |
||||
from documentation and downloads; to forums, member pages, and a patch exchange. You can check |
||||
<A href=https://puredata.info/docs/> https://puredata.info/docs/</A> for more documentation. |
||||
|
||||
<P> |
||||
Most of the interesting news related to Pd shows up on the Pd mailing list, |
||||
maintained by IOhannes zmölnig. To subscribe or browse the archives |
||||
visit: |
||||
<A href="https://lists.puredata.info/listinfo/pd-list"> |
||||
https://lists.puredata.info/listinfo/pd-list</A>. |
||||
|
||||
This is the |
||||
best source of recent information regarding installation problems and bugs. It |
||||
is perfectly reasonable to post "beginner" questions on this list; alternatively |
||||
you can contact msp@ucsd.edu for help. |
||||
|
||||
<P> Many extensions to Pd are announced on the mailing list. In particular, |
||||
for people interested in graphics, there is a 3D graphics rendering package, |
||||
named GEM, based on OpenGL, written by Mark Danks, adapted to Linux by |
||||
Guenter Geiger, and now maintained by IOhannes zmölnig. You can get |
||||
it from: <A href="http://gem.iem.at/">http://gem.iem.at/</A>, via "Find externals" in the |
||||
'Help Menu' or package manager of your Linux distribution. Another option is Ofelia, a Pd external |
||||
that allows you to use openFrameworks and Lua within Pd for creating audiovisual artwork |
||||
or multimedia applications such as games. Get it also via via "Find externals" or from |
||||
<A href="https://github.com/cuinjune/Ofelia">https://github.com/cuinjune/Ofelia</A>. |
||||
|
||||
<P> |
||||
<BR><BR> |
||||
<A href="x2.htm"> next chapter </A><BR> |
||||
<A href="index.htm#s1"> back to table of contents </A> |
||||
<BR><BR> |
||||
</P> |
||||
</div> |
||||
|
||||
|
||||
</BODY> |
||||
</HTML> |
||||
@ -0,0 +1,736 @@ |
||||
<!DOCTYPE html> |
||||
|
||||
<HTML lang="en"> |
||||
<HEAD> |
||||
<meta charset="UTF-8"> |
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
||||
<TITLE>Pd Manual 3</TITLE> |
||||
<meta http-equiv="Content-Type" content="text/html"> |
||||
<link rel="stylesheet" type="text/css" href="pdmanual.css" media="screen"> |
||||
<link rel="icon" type="image/png" href="favicon.ico"> |
||||
</HEAD> |
||||
|
||||
|
||||
<BODY> |
||||
|
||||
|
||||
<div class="butt"> |
||||
|
||||
</div> |
||||
|
||||
<div id=corpus> |
||||
|
||||
<H2>Pd Manual chapter 3: Getting Pd to run</H2> |
||||
|
||||
<P> |
||||
<A href="index.htm#s3"> back to table of contents </A> |
||||
<BR><BR> |
||||
</P> |
||||
|
||||
<P> The following are basic instructions on how to get Pd installed and running |
||||
on your machine. More details are maintained online on the |
||||
<A href=http://www.pure-data.info/>pure-data.info</A> site. |
||||
|
||||
<P>Pd runs under Microsoft Windows, Linux, and macOS. How to |
||||
get Pd up and running depends on your operating system, but the overall strategy |
||||
is the same. You must first get and install it, and then untangle whatever |
||||
problems arise in handling audio and MIDI input and output, and finally get Pd |
||||
to meet its real-time obligations reliably. |
||||
|
||||
<P> Installation instructions are platform-specific; the following three |
||||
sections will describe what to do for various operating systems you might have. |
||||
In case of trouble also consult the Pd mailing list archive on |
||||
<A href="https://lists.puredata.info/listinfo/pd-list"> |
||||
https://lists.puredata.info/listinfo/pd-list</A>. |
||||
, which often has late-breaking news about configuration problems and solutions. |
||||
The rest of this section describes how to get audio and MIDI to work. |
||||
|
||||
<H3> <A id=s1.0> 3.1. Audio and MIDI </A> </H3> |
||||
|
||||
<P> |
||||
To test audio and MIDI, start Pd and select "test Audio and MIDI" from the |
||||
"Media" menu. You should see a window like this: |
||||
|
||||
<CENTER><P> |
||||
<IMG src="fig11.1.png" ALT="test tone patch"> |
||||
</P></CENTER> |
||||
|
||||
<P> First, try to get Pd to play a sine wave over your speakers. The "TEST |
||||
TONE" control at top left turns this on and off. Normally, all the output |
||||
channels are turned on so that when you turn the tone on (to a soft -40 dB or a |
||||
louder -20 dB) you should get output on the first eight of your output channels. |
||||
(If you have fewer than 8 output channels open, the extra |
||||
channels aren't played; and if you have more, this particular patch won't |
||||
use them.) |
||||
|
||||
<P> If there's anything wrong, the most likely outcome is that you will hear |
||||
nothing at all. This could be for any of at least three reasons: Pd might |
||||
have failed to open the audio device; the audio card's output volume might |
||||
be set to zero; or your audio system might not be set to amplify the computer |
||||
output. |
||||
|
||||
<P> The number boxes labeled "AUDIO INPUT" show the levels of incoming |
||||
audio, in dB, with 100 being maximum. (Incoming signals may clip at |
||||
RMS levels below 100; for instance, a sinusoid clips at about 97 dB.) |
||||
Any DC present in the input (such as you get with cheap audio hardware) |
||||
will show up as level unless you turn on the "input hipass" toggle |
||||
at right; then the DC component is filtered out before metering. |
||||
|
||||
<P> To test the quality of audio input and output, turn on "monitor" |
||||
(also at right) which causes the inputs to be played to the outputs at |
||||
unit gain. You should hear a faithful, non-distorted copy of whatever is |
||||
sent through the patch. |
||||
|
||||
<P> It is easy to get two copies of Pd running by accident; on most machines |
||||
only one at a time may be inputting and outputting sound. (Some copy of Pd |
||||
might have audio or MIDI devices open and prevent the copy you're trying to use |
||||
from getting access to them.) Having extra |
||||
copies of Pd around will also eat CPU cycles uselessly. |
||||
|
||||
<P> |
||||
You may be interested in getting only audio output or audio input, or |
||||
you may need both to run simultaneously. By default, Pd will try to run |
||||
both, but if you don't need either input or output, you may find that Pd |
||||
runs more reliably, or at least more efficiently, with the unused direction |
||||
turned off. This may be specified in Pd's command line flags or using the |
||||
"audio settings" dialog panel. |
||||
|
||||
<P> |
||||
Depending on your application you will have a more or less stringent latency |
||||
requirement. Ideally, when any input (audio, MIDI, keyboard, network) is |
||||
available, the outputs (in particular the audio output) should react instantly. |
||||
In real life, it is necessary to buffer the audio inputs and outputs, trying |
||||
always to keep some number of milliseconds ahead of real time to prepare for the |
||||
inevitable occasions where the CPU runs off to service some different task |
||||
from Pd. How small this latency can be chosen depends on your OS and your |
||||
audio driver. |
||||
|
||||
<P> TIP: If Pd starts up but you get distortion or glitches in the audio |
||||
output, this could be either because the "audio I/O buffer" isn't big enough, |
||||
or else because the CPU load of the patch you're running is too great for the |
||||
machine you have, or else because the ADC and DAC are out of sync or even at |
||||
different sample rates. To test for the first possibility, try increasing the |
||||
audio latency in the command line or the "audio settings" dialog (but see also |
||||
under your OS below.) For the second, start up your favorite performance |
||||
monitor program; and for the third, try starting Pd up with ADCs disabled. |
||||
|
||||
<P> In addition to the "test audio and MIDI" patch, the "Media" menu |
||||
contains items for controlling audio and MIDI settings. The first two |
||||
items, "Audio on" and "Audio off", open or close the audio devices and |
||||
start or stop Pd's audio computation. |
||||
|
||||
<P> If there is a choice of |
||||
audio API to make, the Media menu will display them. (On Linux, they are |
||||
OSS, ALSA, and Portaudio; on Windows, you get MMIO and ASIO). On Mac the only |
||||
one is Portaudio. More information about the APIs appears in the sections below. |
||||
|
||||
<P> Selecting an API (even if it's the one already in use), or, alternatively, |
||||
selecting "Audio Settings..." from Preferences, opens |
||||
a dialog panel like this: |
||||
|
||||
<CENTER><P> |
||||
<IMG src="fig11.2.png" ALT="audio settings dialog"> |
||||
</P></CENTER> |
||||
|
||||
<p>The exact choices you get depend on the operating system and API. The sample |
||||
rate controls both audio output and input. The audio throughput delay is |
||||
the nominal amount of time, in milliseconds, that a sound coming into the |
||||
audio input will be delayed if it is copied through Pd straight to the |
||||
output. Naturally you would like this to be as small as possible, but, |
||||
depending on OS, API, and even the specific choice of audio hardware, there |
||||
will be a limit to how small you can make this. You can typically get |
||||
10 msec on Linux (and lower still if you use special tricks), 30 msec on MacOS, |
||||
and 60 msec on Windows (but note that there might be ways that a patient |
||||
Windows user can reduce this). |
||||
|
||||
<P> Next you get a choice of input and output device. If you want to open |
||||
more than one, hit "use multiple devices" and you'll be allowed up to 4 |
||||
in and 4 out. Each audio device is 2 channels by default, but you may |
||||
specify more if your hardware supports it. |
||||
|
||||
Other parameters may be tweaked using the command line; see under |
||||
<A href=#s4> preferences and startup options </A>. |
||||
|
||||
<H6> MIDI </H6> |
||||
|
||||
<p> The "channel message" midi objects in Pd |
||||
such as notein or pgmout will take channels 1-16 to mean the first open MIDI |
||||
port, 17-32 the second one, and so on. The midiin, sysexin, midiout objects |
||||
give you a separate inlet to specify which of the open MIDI port numbers |
||||
you want. |
||||
|
||||
<P> System exclusive MIDI message input and output are theoretically supported |
||||
but does not work uniformly across all operating systems.. |
||||
|
||||
<H3> <A id=s1.1> 3.2. Installing Pd in Microsoft Windows </A> </H3> |
||||
|
||||
<P> Pd should work under any version of Windows since XP. You can download as |
||||
a self-extracting archive (a ".exe" file). Run this and select a destination |
||||
directory when prompted, such as "\pd" or "Program Files\pd". |
||||
|
||||
<P> If for example you put Pd in "C:Program Files\pd", the executable program |
||||
will be "C:Program Files\pd\bin\pd". You can simply adjust your path to |
||||
include C:\pd\bin and then invoke "pd" in a command prompt window. You can also |
||||
make a shortcut to the executable program (left-click on it and drag to the |
||||
desktop, for example.) |
||||
|
||||
<P> Pd requires "TCP/IP networking" to be turned on. This doesn't mean you |
||||
have to be on a real network, but simply that Pd actually consists of two |
||||
programs that make a "network link" (locally) to intercommunicate. |
||||
The first time you run Pd the "Windows Firewall" will ask your permission |
||||
to allow this intercommunication. |
||||
|
||||
<H4> Audio in Microsoft Windows </H4> |
||||
|
||||
<P> |
||||
Pd offers both the ASIO and MMIO APIs in Windows. |
||||
|
||||
<!--- comment out |
||||
|
||||
<P> |
||||
MIDI timing is very poor if you are using simultaneous audio input and output; |
||||
if you suppress either audio input or output things will improve somewhat under |
||||
Window; you can apparently get the jitter down to ~40 msec. On W95 performance is |
||||
simply terrible. W98, with either audio input or output suppressed, offers |
||||
fairly good MIDI timing (~5 msec jitter). The "first edition" used to crash |
||||
occasionally; this might be fixed in the "second edition". |
||||
|
||||
/// end comment out --> |
||||
|
||||
<H4> ASIO </H4> |
||||
|
||||
<P> As of version 0.35 Pd supports ASIO. Invoke Pd as "pd -asio" and, if |
||||
needed, specify "-audiodev" (etc.) flags to specify which device (see |
||||
"the Pd command line" below.) You can also specify a "-blocksize" different |
||||
from the default (256 samples) and "-audiobuf" in milliseconds. Pd will |
||||
round this down to a power of two buffers, each of "-blocksize" in sample |
||||
frames. |
||||
|
||||
<P> TIP: You can use your built-in sound-card with the Universal ASIO Driver For WDM <a href="http://www.asio4all.org/"> http://www.asio4all.org/ </a> |
||||
|
||||
<!--- comment out |
||||
<P> Using MMIO I've been able to get very low latencies (6 msec) using M-audio |
||||
PCI converters (Delta 44). |
||||
/// end comment out --> |
||||
|
||||
<H3> <A id=s1.2> 3.3. Installing Pd in Linux </A> </H3> |
||||
|
||||
<P> What to do depends on which flavor of Linux you are running (e.g., Debian |
||||
or Red Hat). The instructions here should work for Pd 0.33 and up regardless of |
||||
your situation. (If not, you can read the Pd mailing list archives for |
||||
recent problems; if you have found a new problem you're welcome to post it |
||||
to the list.) |
||||
|
||||
<P> Pd is available via the package systems for some Linux distributions, |
||||
but not always in the most recent version possible. It's relatively easy to |
||||
compile your own copy of Pd and that is the approach described here. |
||||
|
||||
<H4> Getting Pd as a .tar.gz </H4> |
||||
|
||||
<P> Before you start, you might want to check that you have the resources Pd |
||||
needs. The main things you need are the C compiler, X windows (including |
||||
the X development package for Pd to link against), TK, and the ALSA "devel" |
||||
headers. It should be |
||||
enough to load "tcl-devel", "tk-devel", and "alsa-devel" packages using |
||||
yum or apt-get. |
||||
|
||||
<P> There are two parallel compilation setups now available. The old one is |
||||
described here; as of 0.43 I still use that but I plan to discontinue this for |
||||
0.44 and start using only the new one. The following description applies to the |
||||
old one. Look in the INSTALL.txt file to see how to use the new one. |
||||
|
||||
<P> |
||||
Download Pd, perhaps from |
||||
<a href="http://msp.ucsd.edu/software.html"> |
||||
http://msp.ucsd.edu/software.html</A> , |
||||
to file such as "pd-linux-033.tar.gz". Open a "shell" |
||||
window, cd to |
||||
the directory containing the file, and type the command, |
||||
<PRE> |
||||
tar xzf pd-linux-033.tar.gz |
||||
</PRE> |
||||
<P>which creates a directory named "pd". I do this from my home directory. |
||||
Next, compile it. "cd" to pd and read the INSTALL.txt, or else just cd |
||||
to "pd/src" and type |
||||
|
||||
<PRE> |
||||
./autogen.sh |
||||
./configure |
||||
make |
||||
</PRE> |
||||
|
||||
<P> You can pass flags to "configure" to customize your compilation: |
||||
|
||||
<PRE> |
||||
To enable debugging (and losing code optimization) add "--enable-debug". |
||||
To use Portaudio, add "--enable-portaudio". |
||||
To put Pd in /usr/bin instead of /usr/local/bin, add "--prefix=/bin". |
||||
</PRE> |
||||
|
||||
<p>Alsa and Jack support should auto-configure, but "--enable-alsa" od |
||||
"--enable-jack" will force their inclusion. |
||||
|
||||
<P> After "make", just type "~/pd/bin/pd" to run pd. |
||||
|
||||
<P> Alternatively, as superuser, you can run "make install" after "make depend" |
||||
and then anyone on your system can just type "pd" to run it. |
||||
|
||||
<H4> Testing audio and MIDI. </H4> |
||||
|
||||
<P> |
||||
Next try audio. We want to know whether audio output works, whether audio |
||||
input works, and whether they work simultaneously. First run "aumix" (or |
||||
any newer audio mixer app) to |
||||
check audio input and output gains and learn which input (mic; line; |
||||
etc.) is "recording". |
||||
Then test audio output by running |
||||
<PRE> |
||||
pd -noadc |
||||
</PRE> |
||||
<P>and selecting "test audio and MIDI" from the "Media" menu. You should see |
||||
a patch. Turn on the test tone and listen. Do the usual where's-the-signal |
||||
business. |
||||
|
||||
<P> |
||||
Then quit Pd and test audio input via |
||||
<PRE> |
||||
pd -nodac |
||||
</PRE> |
||||
<P>Re-open the test patch and hit "meter"; look at the levels. 100 dB is a |
||||
hard clip; arrange gains so that the input signal tops out around 80 or 90, |
||||
but no higher. |
||||
|
||||
<P> Now see if your audio driver can do full duplex by typing "pd" with no |
||||
flags. If you see error messages involving /dev/dsp or /dev/dsp2, you're |
||||
probably not able to run audio in and out at the same time. If on the other |
||||
hand there's no complaint, and if the audio test patch does what you want, you |
||||
might wish to experiment with the "-audiobuffer" flag to see what values of |
||||
audio latency your audio system can handle. |
||||
|
||||
<H3> Audio hardware in Linux </H3> |
||||
|
||||
<P> |
||||
Installing and testing audio and MIDI drivers in Linux can take |
||||
days or weeks. There appears to be no single place where you can get detailed |
||||
information on Linux audio. |
||||
|
||||
<P> |
||||
There are two widely-used driver sets, called "OSS" and "ALSA". ALSA is |
||||
included in the standard Linux kernel since 2.4 or so. However, for some |
||||
audio cards you can find newer versions than are included in the kernel |
||||
releases. You can get ALSA from |
||||
|
||||
<a href="http://www.alsa-project.org/"> |
||||
http://www.alsa-project.org/</A> . |
||||
|
||||
<P> ALSA is able to emulate OSS, so that you can usually run Pd using the |
||||
"OSS" driver settings even if it's actually ALSA that's running. |
||||
|
||||
<P> By default, Pd uses ALSA. You can ask Pd to use ALSA's OSS emulation by |
||||
adding the "-oss" flag to the command line or fooling with the "media" menu |
||||
items. |
||||
|
||||
<P> You can add ALSA devices by name on the Pd command line: |
||||
<PRE> |
||||
pd -alsaadd loupgarou |
||||
</PRE> |
||||
<p>This instructs Pd to offer the 'loupgarou' audio device in the Audio Settings panel. |
||||
|
||||
<H4> Experiences with particular soudcards </H4> |
||||
|
||||
<P> |
||||
Here are some of my own experiences with sound cards so far. See |
||||
also the Pd mailing list archives. |
||||
|
||||
<H6> RME 9652 (Hammerfall) </H6> |
||||
|
||||
<P> This is the best PCI sound card out there; it costs around $500 and has 3 ADAT |
||||
I/O ports and one SPDIF. There is a "baby hammerfall" also, which I think is |
||||
the "9632." DO NOT CONFUSE THE 9652/9632 WITH OTHER RME BOARDS WHICH MIGHT |
||||
NOT WORK WITH PD. |
||||
|
||||
<P> The easiest way to use |
||||
Hammerfall boards in Pd is via ALSA and jack; but you can use ALSA alone: |
||||
<PRE> |
||||
pd -alsa -channels 26 |
||||
</PRE> |
||||
<p>works for me. |
||||
|
||||
<H6> MIDIMAN </H6> |
||||
|
||||
<P>Midiman sells PCI devices (delta 44, 66, 1010, and 1010LT) |
||||
with between 4 and 10 channels in and out, for |
||||
which there are ALSA drivers. These are also very good, and they are a |
||||
bit cheaper than Hammerfalls. The driver name is "ice1712". |
||||
|
||||
<H6> USB sound devices</H6> |
||||
|
||||
<P> Ed Kelly reports success with the Lexicon series of USB 1.0 devices (e.g., |
||||
the Omega Studio; apparently 4 channels in and 4 out). Also known to work well |
||||
is the Edirol box (2 channels in and out). |
||||
|
||||
<P> As of Sept. 2011, the only multi-channel USB device I've been able to use |
||||
with Pd is the Native Instruments Traktor Audio series. (I have the Audio |
||||
Traktor 10 which does indeed get 10 discrete channels in and out; the box is |
||||
designed for turntables and the I/O is all RCA. I haven't yet tested whether |
||||
the inputs are RIAA equalized or flat. To run this device you'll need to |
||||
compile and install an ALSA snapshot from at least September 2011. This won't |
||||
start showing up in Linux distros for at least some months. |
||||
|
||||
<P> The Alsa developer list is reporting progress on the M-audio Ultra series, |
||||
which goes up to 6 in and out (analog) with 2 more as SP/DIF. Things work |
||||
OK for input or output separately but "full duplex" (in and out simultaneously) |
||||
has sync problems. |
||||
|
||||
<H3> <A id="s1.3"> 3.4. Installing Pd in macOS</A> </H3> |
||||
|
||||
<P>Pd version 0.35 and up support macOS. |
||||
Recent versions of Pd require 10.6 or up. |
||||
|
||||
<P> To install Pd you can always download the sources and compile them |
||||
yourself, or (easier) just download the Mac binary from the download page: |
||||
|
||||
<A href="http://msp.ucsd.edu/software.html"> |
||||
http://msp.ucsd.edu/software.html</A> |
||||
|
||||
or from the Pure Data community site: |
||||
|
||||
<A href="https://puredata.info"> |
||||
https://puredata.info</A> |
||||
|
||||
This is in the form of a compressed tar.gz archive; just double click on it to |
||||
extract the Pd application. Open this and you should be running. |
||||
|
||||
<P> You might get various warnings about Pd trying to open an internet port. |
||||
This is normal although some system administrators will prevent you from |
||||
doing this (in which case you can't run Pd on that machine). |
||||
|
||||
<H4> To install on macOS from source: </H4> |
||||
|
||||
<P> |
||||
Whether you've downloaded the source or the "package" you can |
||||
always compile Pd for yourself, whether to make your own improvements, or |
||||
possibly so that you can get the newest version before it shows up compiled for |
||||
macOS. |
||||
|
||||
<P> To be able to compile Pd, you must have Tcl/Tk installed in the standard |
||||
places. I think this is true for all reasonably recent releases of macOS. |
||||
|
||||
<P> Overview: Just as for Linux, extract pd-#.#.#.tar.gz into a directory |
||||
such as ~/pd-0.47-1, cd to ~/pd-0.47-1, run: |
||||
|
||||
<PRE> |
||||
./autogen.sh |
||||
./configure |
||||
make |
||||
</PRE> |
||||
|
||||
<P> Then type ~/pd-0.47-1/bin/pd to a shell and enjoy! |
||||
|
||||
<P> Detailed build instructions can be found in the INSTALL.txt included with |
||||
the Pd source distribution. |
||||
|
||||
<P> If you wish you can put a line such as, |
||||
|
||||
<pre> |
||||
alias pd ~/pd/bin/pd |
||||
</pre> |
||||
|
||||
<P>in the file, ~/.tcshrc, so that you can later just type "pd" to a shell. |
||||
(The |
||||
shell only reads the ~/.tcshrc file on startup, so this won't take effect in |
||||
any existing shells unless you specially type |
||||
<pre> |
||||
source ~/.tcshrc |
||||
</pre> |
||||
<P>to them.) |
||||
|
||||
<P> Follow the general directions above for testing audio and/or MIDI |
||||
as needed. |
||||
|
||||
<P> To get MIDI working, you have to do the macOS magic to get a USB |
||||
MIDI interface installed. I've seen this done with Midisport devices and |
||||
I think you just download the macOS driver and follow directions. |
||||
|
||||
<H3> <A id=s4> 3.5. Preferences and startup options </A> </H3> |
||||
|
||||
<P> Pd's behavior may be customized to instruct it where to find files, which |
||||
audio devices to open, what font size to use, and so on. Most of |
||||
these may also be changed using the various dialogs you can open from Pd's |
||||
menus. Others take effect only when Pd starts up; some of these appear |
||||
on the "startup" dialog and some of them, too cranky to put in a GUI, must |
||||
be typed as <I> command line arguments </I>. |
||||
|
||||
<P> In addition to the Audio and MIDI settings (see |
||||
<A href="#s1.0"> Audio and MIDI </A>), you can customize font size (from the |
||||
"edit" menu), directories to search for files (see |
||||
<A href="#s5"> How Pd searches for files </A>), and additional startup |
||||
parameters described below. |
||||
|
||||
<P> All of these settings may be saved automatically between Pd sessions. |
||||
It is also possible to specify settings directly via the <I> command |
||||
line </I>. (A third mechanism, using configuration files, is deprecated and |
||||
isn't described here.) The Pd command line is described in the next |
||||
section. Command line settings, if given, each override the corresponding |
||||
setting that was saved from Pd. |
||||
|
||||
<P> The startup settings (i.e., those that take effect only when Pd is started) |
||||
are controlled using the "startup..." dialog from the File menu. The |
||||
dialog appears as follows: |
||||
|
||||
<CENTER><P> |
||||
<IMG src="fig11.3.png" ALT="startup dialog"> |
||||
</P></CENTER> |
||||
|
||||
<p>The slots at top each specify a binary "library" for Pd to load on startup. |
||||
These may be for Gem, pdp, zexy, iemlib, cyclone, and so on. Typically, a |
||||
single binary object (an "extern") is left for Pd to load automatically; |
||||
startup library loading is appropriate for collections of many objects |
||||
specified by a single binary library. ( See 4.<a href="x4.htm">Externals </a>for more on externals and how to load them) |
||||
|
||||
<P> The "defeat real-time scheduling" control, if enabled, makes Pd run without |
||||
its usual effort to become a real-time process (whatever this means in the |
||||
operating system you are using.) In Unix, Pd must usually be setuid to allow |
||||
real-time scheduling at all. |
||||
|
||||
<P> The "startup flags" allow you to add to Pd's command line on startup. This |
||||
is specified as described below, except that the initial word, "pd", is |
||||
understood. For example, putting "-rt" in this field sets real-time |
||||
scheduling; "-sleepgrain 1" sets the sleep grain to 1 (see under MIDI below), |
||||
and typing "-rt -sleepgrain 1" does both. |
||||
|
||||
<P> You may save the current settings for future Pd sessions with the |
||||
"save all settings" button; this saves not only the path but all other |
||||
settings as well. |
||||
|
||||
<H6> Command line arguments </A> </H3> |
||||
|
||||
<P>Pd may be run as a "command line" program from your "terminal emulator," |
||||
"shell," or "MS-DOS prompt." In Windows, if Pd is started using a "shortcut" |
||||
it is also run from a command line which you can edit using the "properties" |
||||
dialog for the shortcut. In any operating system, Pd can be called from a |
||||
script (called a <I> batch file </I> on Windows or a <I> shell script </I> |
||||
on macOS or Unix). The command line is just a line of text, which should be |
||||
of the form: |
||||
|
||||
<PRE> |
||||
|
||||
pd [options] [patches to open] |
||||
|
||||
</PRE> |
||||
|
||||
<P>although you may have to specify a path (such as "~/pd/bin/pd" or |
||||
"C:\program files\pd\bin\pd") so your command interpreter can find |
||||
Pd. Possible options include: |
||||
|
||||
<PRE> |
||||
|
||||
audio configuration flags: |
||||
-r <n> -- specify sample rate |
||||
-audioindev ... -- sound in device list; e.g., "2,1" for second and first |
||||
-audiooutdev ... -- sound out device list, same as above |
||||
-audiodev ... -- specify both -audioindev and -audiooutdev together |
||||
-audioaddindev -- add an audio input device by name |
||||
-audioaddoutdev -- add an audio output device by name |
||||
-audioadddev -- add an audio input and output device by name |
||||
-inchannels ... -- number of audio in channels (by device, like "2" or "16,8") |
||||
-outchannels ... -- number of audio out channels (by device) |
||||
-channels ... -- specify both input and output channels |
||||
-audiobuf <n> -- specify size of audio I/O buffer in msec |
||||
-blocksize <n> -- specify audio I/O block size in sample frames |
||||
-sleepgrain <n> -- specify number of milliseconds to sleep when idle |
||||
-nodac -- suppress audio output |
||||
-noadc -- suppress audio input |
||||
-noaudio -- suppress audio input and output (-nosound is synonym) |
||||
-callback -- use callbacks if possible |
||||
-nocallback -- use polling-mode (true by default) |
||||
-listdev -- list audio and MIDI devices |
||||
|
||||
(Linux specific audio:) |
||||
-oss -- use ALSA audio drivers |
||||
-alsa -- use ALSA audio drivers |
||||
-pa -- use portaudio (experimental version 19) |
||||
-alsadev <n> -- obsolete: use -audiodev |
||||
-32bit -- (probably obsolete) -- use 32 bit OSS extension |
||||
-alsaadd <name> -- add a device to the ALSA device list |
||||
|
||||
(Windows specific audio:) |
||||
-mmio -- use MMIO drivers and API |
||||
-asio -- use ASIO drivers and API |
||||
-pa -- synonym for -asio |
||||
|
||||
(Using the JACK API:) |
||||
-jack -- use JACK audio API |
||||
-jackname <name> -- a name for your JACK client |
||||
-nojackconnect -- do not automatically connect pd to the JACK graph |
||||
-jackconnect -- automatically connect pd to the JACK graph [default] |
||||
|
||||
MIDI configuration flags: |
||||
-midiindev ... -- midi in device list; e.g., "1,3" for first and third |
||||
-midioutdev ... -- midi out device list, same format |
||||
-mididev ... -- specify -midioutdev and -midiindev together |
||||
-midiaddindev -- add a MIDI input device by name |
||||
-midiaddoutdev -- add a MIDI output device by name |
||||
-midiadddev -- add a MIDI input and output device by name |
||||
-nomidiin -- suppress MIDI input |
||||
-nomidiout -- suppress MIDI output |
||||
-nomidi -- suppress MIDI input and output |
||||
-ossmidi -- use OSS midi API (Linux only) |
||||
-alsamidi -- use ALSA midi API (Linux only) |
||||
|
||||
general flags: |
||||
|
||||
-path <path> -- add to file search path |
||||
-nostdpath -- don't search standard ("extra") directory |
||||
-stdpath -- search standard directory (true by default) |
||||
-helppath <path> -- add to help file search path |
||||
-open <file> -- open file(s) on startup |
||||
-lib <file> -- load object library(s) (omit file extensions) |
||||
-font-size <n> -- specify default font size in points |
||||
-font-face <name> -- specify default font |
||||
-font-weight <name> -- specify default font weight (normal or bold) |
||||
-verbose -- extra printout on startup and when searching for files |
||||
-noverbose -- no extra printout |
||||
-version -- don't run Pd; just print out which version it is |
||||
-d <n> -- specify debug level |
||||
-loadbang -- do not suppress all loadbangs (true by default) |
||||
-noloadbang -- suppress all loadbangs |
||||
-stderr -- send printout to standard error instead of GUI |
||||
-nostderr -- send printout to GUI (true by default) |
||||
-gui -- start GUI (true by default) |
||||
-nogui -- suppress starting the GUI |
||||
-guiport <n> -- connect to pre-existing GUI over port <n> |
||||
-guicmd "cmd..." -- start alternative GUI program (e.g., remote via ssh) |
||||
-send "msg..." -- send a message at startup, after patches are loaded |
||||
-prefs -- load preferences on startup (true by default) |
||||
-noprefs -- suppress loading preferences on startup |
||||
-prefsfile <file> -- load preferences from a file |
||||
-rt or -realtime -- use real-time priority |
||||
-nrt -- don't use real-time priority |
||||
-sleep -- sleep when idle, don't spin (true by default) |
||||
-nosleep -- spin, don't sleep (may lower latency on multi-CPUs) |
||||
-schedlib <file> -- plug in external scheduler (omit file extensions) |
||||
-extraflags <s> -- string argument to send schedlib |
||||
-batch -- run off-line as a batch process |
||||
-nobatch -- run interactively (true by default) |
||||
-autopatch -- enable auto-patching to new objects (true by default) |
||||
-noautopatch -- defeat auto-patching |
||||
-compatibility <f> -- set back-compatibility to version <f> |
||||
|
||||
</PRE> |
||||
|
||||
<P>Here are some details on some of the audio, MIDI, and scheduler options (but |
||||
see also the next section on file management.) |
||||
|
||||
<H4> multiple devices. </H4> |
||||
|
||||
<P> You can specify multiple MIDI input and output devices. For example, |
||||
"pd -midiindev 3 -midioutdev 4,2" asks for the third MIDI input device and the |
||||
fourth and second MIDI output device. |
||||
|
||||
<P> Audio device selection is similar, except that you can also specify |
||||
channels by device: "-audioindev 1,3 -inchannels 2,8" will try to open device 1 |
||||
(2 channels) and device 3 (8 channels.) |
||||
|
||||
<H4> sample rate. </H4> |
||||
|
||||
<P>The sample rate controls Pd's logical sample rate which need not be that of |
||||
the audio input and output devices. If Pd's sample rate is wrong, time will |
||||
flow at the wrong rate and synthetic sounds will be transposed. If the output |
||||
and input devices are running at different rates, Pd will constantly drop frames |
||||
to re-sync them, which will sound bad. You can disable input or output if this |
||||
is a problem. |
||||
|
||||
<H4> audio buffer size and block size </H4> |
||||
|
||||
<P>You can specify an audio buffer size in milliseconds, typically between 10 and |
||||
300, depending on how responsive your OS and drivers are. If this is set too |
||||
low there will be audio I/O errors ("data late"). The higher the value is, |
||||
on the other hand, the more throughput delay you will hear from the audio |
||||
and/or control inputs (MIDI, GUI) and the audio coming out. |
||||
|
||||
<P> You can also specify the audio block size in sample frames. This is 64 by |
||||
default (except for MMIO for which it's 256), and may be 64, 128, or 256. |
||||
|
||||
<H4> MIDI and sleepgrain</H4> |
||||
|
||||
<P> In Linux, if you |
||||
ask for "pd -midioutdev 1" for instance, you get /dev/midi0 or /dev/midi00 |
||||
(or even /dev/midi). "-midioutdev 45" would be /dev/midi44. In Windows, device |
||||
number 0 is the "MIDI mapper", which is the default MIDI device you selected |
||||
from the control panel; counting from one, the device numbers are card |
||||
numbers as listed by "pd -listdev." |
||||
|
||||
<P> The "sleepgrain" controls how long (in milliseconds) Pd sleeps between |
||||
periods of computation. This is normally the audio buffer divided by 4, but |
||||
no less than 0.1 and no more than 5. On most OSes, ingoing and outgoing MIDI |
||||
is quantized to this value, so if you care about MIDI timing, reduce this to 1 |
||||
or less. |
||||
|
||||
<H3> <A id="s5"> 3.6. How Pd searches for files </A> </H3> |
||||
|
||||
<P>Pd has a search path feature; you specify the path on the command line |
||||
using the "-path" option. Paths may contain any number of files. If you |
||||
specify several files in a single "-path" option they're separated by colons |
||||
in Unix or semicolons in Windows. |
||||
|
||||
<P> You can see and edit the path while Pd is running using the "path..." |
||||
item in the "File / Preferences" menu: |
||||
|
||||
<CENTER><P> |
||||
<IMG src="fig11.4.png" ALT="startup dialog"> |
||||
</P></CENTER> |
||||
|
||||
<P> The path must be correctly set before you load |
||||
a patch or it may fail to find abstractions, etc., that are needed to |
||||
construct the patch. When Pd searches for an abstraction or an |
||||
"extern" it uses the path to try to find the necessary file. The "read" |
||||
messages to qlists and arrays (aka tables) do this too. |
||||
|
||||
<P> If "use standard extensions" is enabled, the usual "extra" directory |
||||
is also searched. This contains standard external objects like "sigmund~" (as well as it's predecessor "fiddle~") and "bonk~", and perhaps much more depending on the distribution of Pd you're using. |
||||
|
||||
<P> You may save the current settings for future Pd sessions with the |
||||
"save all settings" button; this saves not only the path but all other |
||||
settings as well. |
||||
|
||||
<P> Path entries may be relative to the patch directory; for instance, |
||||
if your path has an item, "../sound", and your patch is in "my stuff/all mine", |
||||
then Pd will look in "my stuff/sound". Spaces should be OK in the path to |
||||
the patch, but not in the path entry (../sound) itself. This is useful if |
||||
you have a patch and supporting files (even a supporting snapshot of pd) |
||||
that you want to distribute or carry around together. |
||||
|
||||
<P> Regardless of path, Pd should look first in the directory containing |
||||
the patch before searching down the path. Pd does not automatically look |
||||
in the <I> current directory </I> however; to enable that, include "." in |
||||
the path. The "extra" directory, if enabled, is searched last. |
||||
|
||||
<P> Filenames in Pd are always separated by (Unix-style) forward slashes, even |
||||
if you're on Windows (which uses backslashes). This is so that patches can be |
||||
ported more easily between operating systems. On the other hand, if you |
||||
specify a filename on the command line (as in "pd -path c:\pdlib") the file |
||||
separator should agree with the operating system. <BR> |
||||
|
||||
<P> A filename specified in a patch with any "/" characters in it (such as |
||||
"../sounds/sample1.wav") causes Pd to to look both in the path and relative |
||||
to the directory containing the patch. You may also invoke externs that way. ( See 4.<a href="x4.htm">Externals </a>for more on externals and how to load them) |
||||
|
||||
<P> As of version 0.35, there may be spaces in the path to Pd itself; also, |
||||
the "openpanel" and "savepanel" objects can handle spaces. Spaces in the |
||||
path should work as of version 0.38. |
||||
|
||||
<P> |
||||
<BR><BR> |
||||
<A href="x4.htm"> next chapter </A><BR> |
||||
<A href="index.htm#s3"> back to table of contents </A> |
||||
<BR><BR> |
||||
</P> |
||||
|
||||
</div> |
||||
|
||||
|
||||
</BODY> |
||||
</HTML> |
||||
|
||||
|
||||
@ -0,0 +1,600 @@ |
||||
<!DOCTYPE html> |
||||
|
||||
<HTML lang="en"> |
||||
<HEAD> |
||||
<meta charset="UTF-8"> |
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
||||
<TITLE>Pd Manual 4</TITLE> |
||||
<meta http-equiv="Content-Type" content="text/html"> |
||||
<link rel="stylesheet" type="text/css" href="pdmanual.css" media="screen"> |
||||
<link rel="icon" type="image/png" href="favicon.ico"> |
||||
</HEAD> |
||||
|
||||
|
||||
<BODY> |
||||
|
||||
|
||||
<div class="butt"> |
||||
|
||||
</div> |
||||
|
||||
<div id=corpus> |
||||
|
||||
<H2>Pd Manual chapter 4: externals</H2> |
||||
|
||||
<P> |
||||
<A href="index.htm#s4"> back to table of contents </A> |
||||
<BR><BR> |
||||
</P> |
||||
|
||||
|
||||
<H3> <A id=> 4. Externals </A> </H2> |
||||
|
||||
<p> This section explains what are external objects and libraries. It also |
||||
describes everything on how to install and load them in Pure Data. |
||||
|
||||
<p>You can write your own external objects that you and others can use in |
||||
their Pd applications in C or (if you're smart and brave) in C++ or FORTRAN. |
||||
In the "6.externs" subdirectory of the documentation you can find simple |
||||
examples of externals with their source code and test patches. |
||||
|
||||
<p>There’s also an excellent guide to writing externals project by IOhannes |
||||
zmölnig at <a href="https://github.com/pure-data/externals-howto">https://github.com/pure-data/externals-howto</a>. Check also the |
||||
pd-lib-builder project (a helper makefile for Pure Data external libraries by |
||||
Katja Vetter) at <a href="http://github.com/pure-data/pd-lib-builder"> http://github.com/pure-data/pd-lib-builder<a/> |
||||
|
||||
|
||||
<H3> <A id=s1> 4.1 External Objects & Libraries </A> </H2> |
||||
|
||||
<H3> <A id=s1.1> 4.1.1 What are: Vanilla Objects, Internals & Externals? </A> </H3> |
||||
|
||||
<p> Internal objects come as part of the Pd binary, whereas external objects |
||||
are separate from it. The main Pd distribution (a.k.a. “Pd Vanilla”) also comes |
||||
with a few “extra” objects that are not part of its binary. Therefore, the set of |
||||
“vanilla objects” (the built-in objects in Pd) include internals and externals. |
||||
Nonetheless, “externals” mostly refer objects not available in the Pd Vanilla |
||||
distribution, that you need to download and install them properly so they can |
||||
be loaded into Pd patches. |
||||
|
||||
<p> To get a full list of all objects in Pd Vanilla, go to the <b>Help</b> menu and |
||||
then select <b>List of Objects</b>, or alternatively right click on an empty spot of a |
||||
patch’s window and select “help” - this loads the help-intro.pd file (see below). |
||||
|
||||
|
||||
<p><img src=fig4.1.png > |
||||
|
||||
<br> |
||||
|
||||
<p> The set of externals that come with Pd are available in the ‘extra’ library |
||||
and is located in a folder named “extra” inside the Pd application. These |
||||
appear at the very end of the “help-intro.pd” and can also be viewed in the |
||||
Help Browser menu (Help => Browser). See figure below, which shows how |
||||
the browser looks in a fresh install of Pd and lists the objects in the extra |
||||
folder. |
||||
|
||||
<p><img src=fig4.2.png > |
||||
|
||||
<br> |
||||
|
||||
|
||||
<H3> <A id=s1.2> 4.1.2. What are the Types of External Objects? </A> </H3> |
||||
|
||||
<p> An object in Pd can be either a patch - meaning a Pd file (a.k.a |
||||
abstraction) - or a compiled binary (note that a binary can contain only one or |
||||
several external objects, as discussed further on). |
||||
|
||||
|
||||
<H3> <A id=s1.2.1> 4.1.2.1. Compiled objects: </A> </H3> |
||||
|
||||
<p> These are Pd objects compiled to binaries from programming code (like |
||||
in C or C++). They have to be compiled for your operating system, which |
||||
means the binaries have different extensions according to each platform. For |
||||
instance: |
||||
|
||||
<table> |
||||
<thead valign="bottom"> |
||||
<tr><th>Operating System</th> |
||||
<th>CPU-architecture</th> |
||||
<th>filename</th> |
||||
</tr> |
||||
</thead> |
||||
<tbody valign="top"> |
||||
<tr><td>Linux</td> |
||||
<td><em>unspecified</em> |
||||
(any architecture)</td> |
||||
<td><code>my_lib.pd_linux</code></td> |
||||
</tr> |
||||
<tr><td>Linux</td> |
||||
<td>i386 (Intel/AMD 32bit)</td> |
||||
<td><code>my_lib.l_i386</code></td> |
||||
</tr> |
||||
<tr><td>Linux</td> |
||||
<td>amd64 (Intel/AMD 64bit)</td> |
||||
<td><code>my_lib.l_amd64</code></td> |
||||
</tr> |
||||
<tr><td>Linux</td> |
||||
<td>arm (e.g. RaspberryPi)</td> |
||||
<td><code>my_lib.l_arm</code></td> |
||||
</tr> |
||||
<tr><td>Linux</td> |
||||
<td>arm64</td> |
||||
<td><code>my_lib.l_arm64</code></td> |
||||
</tr> |
||||
<tr><td>macOS</td> |
||||
<td><em>unspecified</em> |
||||
(any architecture)</td> |
||||
<td><code>my_lib.pd_darwin</code></td> |
||||
</tr> |
||||
<tr><td>macOS</td> |
||||
<td>fat (multiple archs)</td> |
||||
<td><code>my_lib.d_fat</code></td> |
||||
</tr> |
||||
<tr><td>macOS</td> |
||||
<td>PowerPC</td> |
||||
<td><code>my_lib.d_ppc</code></td> |
||||
</tr> |
||||
<tr><td>macOS</td> |
||||
<td>i386 (Intel 32bit)</td> |
||||
<td><code>my_lib.d_i386</code></td> |
||||
</tr> |
||||
<tr><td>macOS</td> |
||||
<td>amd64 (Intel 64bit)</td> |
||||
<td><code>my_lib.d_amd64</code></td> |
||||
</tr> |
||||
<tr><td>macOS</td> |
||||
<td>arm64 (Apple Silicon)</td> |
||||
<td><code>my_lib.d_arm64</code></td> |
||||
</tr> |
||||
<tr><td>Windows</td> |
||||
<td><em>unspecified</em> |
||||
(any architecture)</td> |
||||
<td><code>my_lib.dll</code></td> |
||||
</tr> |
||||
<tr><td>Windows</td> |
||||
<td>i386 (Intel/AMD 32bit)</td> |
||||
<td><code>my_lib.m_i386</code></td> |
||||
</tr> |
||||
<tr><td>Windows</td> |
||||
<td>amd64 (Intel/AMD 64bit)</td> |
||||
<td><code>my_lib.m_amd64</code></td> |
||||
</tr> |
||||
</tbody> |
||||
</table> |
||||
|
||||
|
||||
<H3> <A id=s1.2.2> 4.1.2.2. Abstractions:</A> </H3> |
||||
|
||||
<p>You can have a Pd patch behave like an object by loading it into other |
||||
patches - these are usually called “abstractions”. Note that some of the |
||||
externals in “extra” are abstractions (for instance, rev1~ or hilbert~). Like any |
||||
other Pd patch, an abstraction may contain any kind of objects (internals, |
||||
compiled externals and even other abstractions). |
||||
|
||||
|
||||
|
||||
|
||||
<H3> <A id=s1.3> 4.1.3. What are External Libraries? </A> </H3> |
||||
|
||||
<p>In practical terms, an external library is a collection of external objects of any kind (abstractions or compiled objects). But when it comes to compiled objects, a library can provide several objects as a <b>single binary pack</b> or as a <b>set of |
||||
separate binaries</b> (where each object has its own binary). |
||||
|
||||
<p>The “classic” library format is a single binary pack (with two or more |
||||
externals), but splitting into separate binaries became a very common |
||||
practice. A single external binary (not part of any set of objects) is still, |
||||
technically, a library with just one object. But again, the prevailing idea is that |
||||
a library is just a set of objects. |
||||
|
||||
<p> It’s important to note that there are differences on how externals are |
||||
loaded depending if they’re a single binary pack or a set of separate binaries |
||||
(as explained in the next subsections). |
||||
|
||||
|
||||
|
||||
<H3> <A id=s1.4> 4.1.4. What are the types of External Libraries? </A> </H3> |
||||
|
||||
<p>Libraries can come in all sorts of ways; as only a collection of |
||||
abstractions (like "list-abs"), only compiled objects, or both. It can even mix |
||||
compiled externals both as a <b>set of separate binaries</b> and a <b>single binary |
||||
pack</b>. Basically, any combination is possible for a set of external. |
||||
|
||||
<p>One example that combines all external options is <i>Cyclone</i> (since version 0.3), |
||||
which provides most of its objects as a <b>set of separate binaries</b>, but also includes |
||||
a small collection of 12 objects as a <b>single binary pack</b> plus a few abstractions. |
||||
|
||||
<H3> <A id=xx1>Wrapping up Part 1)</A> </H3> |
||||
<UL> |
||||
|
||||
<LI> <b>Internal objects:</b> Objects that are part of Pd Vanilla's binary. |
||||
<LI> <b>External objects:</b> Objects that are <u>NOT</u> part of Pd Vanilla's binary. |
||||
<LI> <b>Vanilla objects:</b> Built-in objects in the Pd Vanilla distribution |
||||
(including internals and a small collection of externals - the "extra" objects). |
||||
<LI> <b>Types of external objects:</b> Compiled binaries or Abstractions. |
||||
<LI> <b>External Library:</b> Collection of external objects in any form, be it a |
||||
<u>single binary pack</u> containing several objects, a <u>set of separate binaries</u> / |
||||
abstractions or any combination of them. |
||||
</UL> |
||||
<br> |
||||
<br> |
||||
<hr> |
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<H3> <A id=s2>4.2. Installing External Objects and Libraries |
||||
</A> </H3> |
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<p>Installing externals in Pd is quite simple, all you need to do is download |
||||
your externals from somewhere, such as from Pd Vanilla directly, and include |
||||
them in a proper folder. |
||||
|
||||
<H3> <A id=s2.1>4.2.1. Where to include the externals?</A> </H3> |
||||
|
||||
<p>Currently, when launching for the first time with a fresh install, Pd asks if |
||||
you want to create a documents directory for patches that includes an |
||||
“externals” subdirectory. This externals folder is where it’s advised to include |
||||
external libraries and it’s automatically included in the user added search |
||||
paths (under Preferences => Path), see figure below. |
||||
|
||||
<p><img src=fig4.3.png > |
||||
|
||||
<br> |
||||
|
||||
|
||||
<p>We see in the screenshot above that the “Pd” folder is created |
||||
under ~/Documents, and inside it we have the externals subfolder. |
||||
Even if you did not create this folder, here is where you can create it by |
||||
clicking the “Reset” button under “Pd Documents Directory”. |
||||
|
||||
|
||||
<p>Externals can actually be anywhere in your computer, but Pd must |
||||
know where to look for them. Pd looks for files (including externals) in the |
||||
user added search paths, but it also searches in other folders not listed there |
||||
such as: the same folder that your patch is saved on |
||||
(the <u>Relative Path</u>) and the <u>Standard Paths</u>, which are: |
||||
<UL> |
||||
<LI>A) <u>Application-specific</u>: The "extra" folder inside a particular Pure Data |
||||
application. |
||||
<LI>B) <u>User-specific</u>: A system folder for a specific user in the machine. |
||||
<LI>C) <u>Global</u>: A system folder for all users on the machine. |
||||
</UL> |
||||
|
||||
<p>Officially, there’s only one ‘Standard Path’ which is the ‘extra’ folder. |
||||
The others are not automatically created by Pd and are part of an old |
||||
structure. Currently, the best practice is to use the default external folders or |
||||
user added paths, but these other options are documented here anyway and |
||||
may be useful in some edge cases. |
||||
|
||||
|
||||
<p> The <u>Global</u> folder |
||||
affects all Pure Data Applications for all users. The <u>User-specific</u> folder affects |
||||
all Pure Data Applications for that user. And since you can have different |
||||
versions of Pd installed in your system, the <u>Application-specific</u> folder affects |
||||
only that particular Pd Application - multiple |
||||
Pd applications can be of different versions (an older and a newer one or |
||||
both 32-bit and 64-bit). For reference, here’s the list of the Standard Paths for |
||||
all operating systems: |
||||
|
||||
|
||||
<p>A) macOS: |
||||
<UL> |
||||
<LI><u>Application-specific</u>: <mark><b>/$PdPath/Contents/Resources/extra</b></mark> - this is |
||||
inside the Pd Application (like Pd-0.49-1 in ~/Applications); right click it and |
||||
choose "Show Package Contents", then navigate to "Resources/extra". |
||||
<LI><u>User-specific</u>: <mark><b>~/Library/Pd</b></mark> (/Users/user_name/Library/Pd) |
||||
<LI><u>Global</u>: <mark><b>/Library/Pd</b></mark> |
||||
|
||||
</UL> |
||||
|
||||
<p>B) Windows: |
||||
<UL> |
||||
<LI><u>Application-specific</u>: <mark><b> %ProgramFiles(x86)%\Pd\extra</b></mark> (for 64-bit |
||||
OS and 32-bit Pd) or %ProgramFiles%\Pd\extra; this is |
||||
inside the Pd Application (usually in C:\Program Files). |
||||
This folder needs to be set to writeable. |
||||
<LI><u>User-specific</u>: <mark><b> %AppData%\Pd</b></mark> |
||||
(usually in C:\Users\user_name\AppData\Roaming\Pd). |
||||
<LI><u>Global</u>: <mark><b> %CommonProgramFiles%\Pd</b></mark> |
||||
(usually in C:\Program Files\Common Files\Pd). |
||||
|
||||
</UL> |
||||
|
||||
C) GNU/Linux: |
||||
|
||||
<UL> |
||||
|
||||
<LI><u>Application-specific</u>: <mark><b> /usr/lib/pd/extra</b></mark> if installed via a package |
||||
manager (apt-get) or /usr/local/lib/pd/extra if compiled by yourself. |
||||
<LI><u>User-specific</u>: <mark><b> ~/.local/lib/pd/extra</b></mark> (preferred since version Pd-0.47-1) |
||||
or ~/pd-externals (deprecated but still usable). |
||||
<LI><u>Global</u>: <mark><b> /usr/local/lib/pd-externals</b></mark>. |
||||
</UL> |
||||
|
||||
<H3> <A id=s2.2>4.2.2. How to Download Externals from Pd Vanilla?</A> </H3> |
||||
|
||||
<p>Since version 0.47-0, Pd Vanilla has its own external manager! This is a |
||||
built in .tcl plug-in named "deken" (check <a href="https://github.com/pure-data/deken"> https://github.com/pure-data/deken </a> |
||||
for reference). Open it by selecting the <b>Help => Find externals</b> tab. Then you |
||||
can type and search for object name, library name or both. The wildcard '*' can be used |
||||
to broaden the search, or an exact name can be used instead. All available versions of |
||||
the library/external specific for your operating system will be shown to you. See figure below. |
||||
|
||||
|
||||
<p><img src=deken.gif > |
||||
|
||||
<br> |
||||
|
||||
<p>When you double-click on the version you want, by default Pd downloads it to |
||||
"~/Documents/Pd/externals". |
||||
<br> |
||||
<br> |
||||
<hr> |
||||
<H3> <A id=s3>4.3. Loading Externals </A> </H3> |
||||
|
||||
<p>The current best practice is to use the declare object to search for, load and manage |
||||
externals, but there are alternatives. |
||||
|
||||
<p>If the object is from a library that is distributed as a single binary pack, |
||||
this binary needs to be pre loaded so Pd can create its externals. This is done |
||||
either with declare or manually via Preferences => Startup. |
||||
|
||||
<p>If the external library only contains abstractions or objects compiled as |
||||
a set of separate binaries, Pd just needs to know its path. Again, this can be |
||||
done with declare or manually via Preferences => Path, but yet another |
||||
option here is to use slash declarations as we'll see later. |
||||
|
||||
<H3> <A id=s3.1>4.3.1. Using the [declare] object:</A> </H3> |
||||
|
||||
<p>The declare object can be used to add search paths or load libraries. When |
||||
adding a path, it behaves quite similarly to adding search paths to the |
||||
user added paths (under Preferences => Path). The difference is that this will |
||||
only work for the patch that contains the declare object - unlike using path, |
||||
which loads permanently for any patch. |
||||
|
||||
<p>As for loading a library, once Pd loads it (via [declare] or startup) it |
||||
sticks with it. This means that if you use [declare] to load a library, it will |
||||
also be loaded if you create a new patch without any [declare] object. |
||||
|
||||
<H3> <A id=s3.1.1>4.3.1.1. [declare -path]:</A> </H3> |
||||
|
||||
<p>Let's take for an example the <a href="http://github.com/porres/pd-else"> ELSE</a> library. |
||||
This library contains separate binaries and abstractions, so Pd only needs to know its location |
||||
path. We then use the '-path' flag as in [declare -path else]. This makes Pd look for a folder |
||||
named 'else' to add it to the search path for that patch only. When and if it succeeds in finding |
||||
this folder with [declare], this is where Pd will prioritize the search of objects and other files, |
||||
moving on to other possible search places if nothing is found. |
||||
|
||||
<p>But where does Pd look for the 'else' folder? Well, the -path flag is first meant |
||||
to search in the Relative Path, but if it doesn't find it, it falls back to the |
||||
User Added Paths and Standard Paths. So let’s say you put the ELSE library folder in |
||||
“~/Documents/Pd/externals”, which is the current best practice, Pd will know to look |
||||
for it there and will find it! |
||||
|
||||
<p> Now, in the case of a single external, the best practice is to include it in |
||||
a folder with the same name in “~/Documents/Pd/externals”. An example, the freeverb~ |
||||
external should be in “~/Documents/Pd/externals/freeverb~”. In this situation, you don’t |
||||
need to add the external folder to the path, manually or use [declare]. This is because |
||||
when you tell Pd to look for an external, if it finds a folder with the same name as the |
||||
external, it'll know to search inside that folder for the external! |
||||
|
||||
|
||||
<H3> <A id=s3.1.2>4.3.1.2. [declare -lib]:</A> </H3> |
||||
|
||||
<p>The '-lib' flag is needed for the classic Pd library format, which |
||||
is a single binary pack with many externals. One such example is the |
||||
<a href="https://git.iem.at/pd/zexy/"> zexy </a> library. So you should |
||||
download and have the 'zexy' folderr in “~/Documents/Pd/externals/zexy”. |
||||
Now you can use [declare -lib zexy] to load the external binary. In the |
||||
same way as explained with the freeverrb~ example, the binary is inside |
||||
a folder with the same name. So Pd will search for the external in |
||||
“~/Documents/Pd/externals", will find the 'zexy' folder and know to |
||||
search for the zexy binary in it. This means you don't need to bother in |
||||
using [declare] to define the search path. |
||||
|
||||
<p>Note that it may be possible for you to load a library binary as an object if the |
||||
developer wished to. But it's still advisable to use either "Startup" or [declare -lib], |
||||
because this way you are sure the library is preloaded before Pd tries to create |
||||
other objects in your patch. |
||||
|
||||
<p>For more details on how [declare] works, please check its help file! |
||||
|
||||
<H3> <A id=s3.2>4.3.2. Load via Path and Startup:</A> </H3> |
||||
|
||||
<p>We'll now see the differeces between using [declare] or using "Path" and "Startup". |
||||
|
||||
|
||||
<H3> <A id=s3.2.1>4.3.2.1. User added Path:</A> </H3> |
||||
|
||||
<p>One big difference in adding a search path in "Preferences => Path" "is that this |
||||
permanently adds the path and work every time Pd starts and for any patch you open. |
||||
When you use [declare], the path is loaded only for its owning patch and loaded |
||||
abstractions. Moreover, if you have an abstraction with [declare -path], it'll only |
||||
work for that abstraction and not the parent patch. Hence, [declare] allows a much |
||||
better control and management of paths. But you may want to permanently add a path |
||||
in your own system if you know exactly what you have and what you need. |
||||
|
||||
<p>We’ve seen that even if you have a folder into “~/Documents/Pd/externals” you |
||||
still need to tell Pd to look for it. You can manually add a User Added Paths in |
||||
Preferences => Path by clicking “New”. |
||||
|
||||
<p>Another possibility is that under deken’s preferences tabs you can click |
||||
on “Add newly installed libraries to Pd’s search Path”, which adds downloaded |
||||
libraries to the user added search paths. |
||||
|
||||
<p>Note also that having a user added search path will not make it have search priority |
||||
like it happens when you use [declare]. In this case, the path relative to the patch |
||||
will always have top priority! |
||||
|
||||
<H3> <A id=s3.2.2>4.3.2.2. Startup:</A> </H3> |
||||
|
||||
<p>"Preferences => Startup" loads a window that says <i>"Pd libraries to load on startup"</i>. |
||||
This is where you can manually and permanently load single binary pack libraries. But since |
||||
they're only needed during startup, you need to restart Pd so this takes effect. The startup |
||||
is also used for configuring Pd in many ways, |
||||
see <a href="x3.htm#s4">3.6. Preferences and startup options</a> for reference. |
||||
|
||||
<p><img src=fig4.5.png > |
||||
<br> |
||||
|
||||
<p>As we’ve seen with ‘zexy’, it’s common that the name of the binary is |
||||
the same as the library’s, so you don’t need to worry about adding it to the path. |
||||
Another example is the ‘cyclone’ library. As previously mentioned, Cyclone |
||||
includes objects as abstractions, as a <u>set of separate binaries</u> and |
||||
also has a set a <u>single binary pack</u> (which loads objects with non |
||||
alphanumeric names that need to be loaded as such to avoid issues). One |
||||
particularity of cyclone is that loading its binary will also force Pd to add its |
||||
path to the search paths, so you don’t need to bother adding it to the path as |
||||
well in order to be able to load its abstractions or separate binaries. Another |
||||
example that uses this feature is <a href="https://github.com/umlaeute/Gem"> Gem </a>, |
||||
which loads as a binary pack but also includes a few abstractions that rely on the path search. |
||||
Note, however, that unlike using [declare], this does not enforce a search priority! |
||||
Hence, for example, you may prefer to use [declare -path cyclone -lib cyclone] instead. |
||||
|
||||
<p>It all depends on the developer, but it is a common and good practice that |
||||
when you load a library, Pd’s terminal window will print something to tell us |
||||
that the libraries were loaded successfully. Here’s a screenshot of the result |
||||
of loading cyclone and zexy via the startup (same happens if you load them |
||||
via [declare], clearly). |
||||
|
||||
<p>Note that when you load a library like this or via [declare -lib], all of its external |
||||
objects are loaded in Pd and they have search priority. This may cause issues discussed |
||||
on the next section. |
||||
|
||||
<p><img src=fig4.6.png > |
||||
<br> |
||||
|
||||
<H3> <A id=s3.3>4.3.3. Slash declarations:</A> </H3> |
||||
|
||||
<p>What is this and how does it work? Let’s say you’ve downloaded the ELSE library into |
||||
~/Documents/Pd/externals. Instead of using [declare -path else] or adding the |
||||
ELSE folder to the user added paths manually, you can just prepend “else/“ |
||||
before an object name. This will make Pd look for this object in a folder called |
||||
‘else’ in one of its search paths (which includes ~/Documents/Pd/externals) |
||||
and find it! Here’s an example: |
||||
|
||||
|
||||
<p><img src=fig4.7.png > |
||||
|
||||
|
||||
<p>Now, what’s the need or advantage of this over using [declare] or adding the folder to the |
||||
user added paths? This can be an option that some people may prefer for the simple fact that |
||||
it's just clearer from which library folder we're loading the external. But there are some rare |
||||
cases where this is the only way to guarantee you have loaded the correct external, which is a |
||||
problem when you have too many libraries in your system and using more than one that has an external |
||||
with the same name. Hence, some external libraries like 'Cyclone' and 'ELSE' use this in the |
||||
documentation of the help files to make sure you load the correct external. |
||||
|
||||
<p>Note, however, that this is not possible for an external that is loaded as |
||||
part of a single binary pack, unless the developer uses a workaround to add |
||||
this possibility as alternative. |
||||
|
||||
<p>The issue with [declare] or adding a path to the user added paths is that it'll respect a search |
||||
order. Whatever path is added first in the search list order has a priority, and where ever Pd finds |
||||
an external first, it'll load it and stop searching elsewhere. Again, this kind of problem is not that |
||||
common, but you may be able to sort this issue by setting the desired order. This is quite easy in [declare], |
||||
which ever -path comes first in the list has a priority. You can try this if you want to avoid slash |
||||
declarations when you run into this rare issue. |
||||
|
||||
<p>Such conflicts can also happen when you're loading single binary pack libraries. The problem is that |
||||
once they get loaded, all of its external objects are now part of Pd and have a priority in the search. |
||||
Here's an example, the 'ceammc' library is a single binary pack and it included an object called [xfade~]. |
||||
The ELSE library has separate binaries for each object and also has one called [xfade~]. If you're using both |
||||
libraries, ceammc's [xfade~] object will have priority and it deosn't help you to have [declare -path else]. |
||||
You can then use [else/xfade~] to specifically call ELSE's [xfade~] instead. |
||||
|
||||
<p>It was mentioned how a library name prefix may also be possible in the context of single binary packs. |
||||
The ceammc library offers this, so you can also load its [xfade~] object as [ceammc/xfade~]. But note that |
||||
this still requires you to preload the binary (via startup or [declare]). The slash declaration here was only |
||||
possible because the developer added the 'ceammc/xfade~' name as an alternative option in the code. So it is |
||||
just a hack to improve the limitation of Pd in handling namespaces. Another library that does this is Cyclone, |
||||
which carries a sublibrary with 12 objects with non alphanumeric names, such as [>~]. By using the same |
||||
trick, you can create the [>~] object as [cyclone/>~]. Another single binary pack library that has [>~] is zexy, |
||||
so this way you can make sure you're getting cyclone's instead. |
||||
|
||||
<p>These issues might be clear if you better understand how Pd works when loading externals. See next subsection. |
||||
|
||||
<H3> <A id=s4>4.4. How external binaries are loaded</A> </H3> |
||||
|
||||
<p>Once you make sure Pd can load an external binary, this is what happens when you |
||||
create it. Whenever you type the name of an object (into an "object" box) that |
||||
Pd doesn't yet know about, Pd looks for the object file named, for instance, as |
||||
"profile.pd_linux". Pd looks first in a path defined by [declare] (if any, of course), |
||||
then in the directory containing the patch, then in directories listed as user added |
||||
paths in the orderr they are listed, then in the standard paths. As soon as Pd finds |
||||
the object in this search order, it'll stop searching further more and will add the |
||||
found object to its "class list", which is the set of all Pd classes you can use. |
||||
Pd then tries to create the object you asked for, and if everrything is fine with it, |
||||
this happens successfully (creation errors are given otherwise). In the case of a single |
||||
binary pack, all the externals it contains get preloaded in Pd, even though they're |
||||
only created in object boxes when you require them. |
||||
|
||||
<p>Once an external object's binary is in Pd's memory, there is no real difference between |
||||
it and a native object. They're all seen equally now in Pd. Once a new separate binary or |
||||
single binary pack is loaded, it's there for the duration of your Pd session. This means |
||||
that if you replace the binaries, the objects won't be updated even if you recreate them. |
||||
You can also even delete the binary as Pd now carried it for good. Hence, if you're working |
||||
on the development of an object's binary and decide to change it, you have to exit and re-enter |
||||
Pd to get the change to take. |
||||
|
||||
<p>Let us just make the distinction that external abstractions work quite differently! As they |
||||
get updated any time they’re updated and reloaded! |
||||
|
||||
|
||||
<H3> <A id=s3.3>4.4.1. Overriding objects (externals and native):</A> </H3> |
||||
|
||||
<p>We've seen that Pd loads and sticks to an external. But this can get overridden. |
||||
We've actually seen that already. For instance, you create [xfade~] from ELSE, then |
||||
you load ceammc's binary that also has an [xfade~] object. Now Pd only knows about |
||||
[xfade~] from ceammc! It's been also noted how cyclone and zexy have objects with |
||||
the same name. If you first load cyclone's binary and zexy's later, zexy's objects |
||||
with the same name (such as [>~]) will override and prevail. |
||||
|
||||
<p>And here's an interesting feature, you can also override internal Pd Vanilla |
||||
objects with externals! Say you have an external called [phasor~]. It it's a |
||||
single binary, you can force Pd to find it with slash declarations. Otherwise, if |
||||
it's a binary pack, you can load as any other library and if it has objects with the |
||||
same name as vanilla's internals, they get overridden! But Pd still keeps a copy of |
||||
the old one and renames it by appending "_aliased", so you can still load the old |
||||
"phasor~", for instance, as <b>[phasor~_aliased]</b>. You probably don't want to mess overriding |
||||
internals, but it makes sense if you provide new versions with more features but fully |
||||
backwards compatible. |
||||
|
||||
<H3> <A id=s4>4.5. Search order for loading objects</A> </H3> |
||||
|
||||
<p>This information has been provided in pieces throughout this section of the Manual. But |
||||
now well wrap it up after all the information has been presented. |
||||
|
||||
<p>So, whenever you tell Pd to create an object in its box, this is what happens. |
||||
|
||||
<p><b>First</b> it searches in its object list. This includes all of Pd's internals and |
||||
other externals that may have been previously loaded. |
||||
|
||||
<p><b>Second</b>, it moves on to possible paths. And if you have [declare -path] in your patch, |
||||
the defined path(s) has/have priority respecting the order they are listed from left to |
||||
right. |
||||
|
||||
<p><b>Third</b> is time to search the path relative to the patch. |
||||
|
||||
<p><b>Fourth</b> it goes to the user added paths, defined at "Preferences => Path". An order |
||||
is also respeccted, from top to bottom. |
||||
|
||||
<p><b>Fifth</b> and last, it searches the "standard paths", which includes the 'extra' library |
||||
provided by the Pd Vanilla distribution. Note you can use [declare -stdpath ./] to force |
||||
priority to search this folder! |
||||
|
||||
<P> |
||||
<BR><BR> |
||||
<A href="x5.htm"> next chapter </A><BR> |
||||
<A href="index.htm#s4"> back to table of contents </A> |
||||
<BR><BR> |
||||
</P> |
||||
|
||||
</div> |
||||
|
||||
|
||||
</BODY> |
||||
</HTML> |
||||
@ -0,0 +1,250 @@ |
||||
<!DOCTYPE html> |
||||
|
||||
<HTML lang="en"> |
||||
<HEAD> |
||||
<meta charset="UTF-8"> |
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
||||
<TITLE>Pd Manual 6</TITLE> |
||||
<meta http-equiv="Content-Type" content="text/html"> |
||||
<link rel="stylesheet" type="text/css" href="pdmanual.css" media="screen"> |
||||
<link rel="icon" type="image/png" href="favicon.ico"> |
||||
</HEAD> |
||||
|
||||
<BODY> |
||||
|
||||
|
||||
<div class="butt"> |
||||
|
||||
</div> |
||||
|
||||
<div id=corpus> |
||||
|
||||
|
||||
<p><a class=green href="x6.htm#more-mac" >back to ch6</a> <a href="index.htm#s6"> back to table of contents </a></p> |
||||
|
||||
|
||||
|
||||
<h3 id="s6.4.1">6.4.1 macOS resources</h3> |
||||
|
||||
<p>Directory pure-data/mac contains support files for building a Pure Data macOS application |
||||
bundle and supplementary build scripts for compiling Pd on Macintosh systems, as |
||||
it is built for the ‘vanilla’ releases on msp.ucsd.edu.</p> |
||||
|
||||
<h3 id="Pd.macOS.app">Pd macOS app</h3> |
||||
|
||||
<p>In a nutshell, a monolithic macOS “application” is simply a directory structure |
||||
treated as a single object by the OS. Inside this bundle are the compiled |
||||
binaries, resource files, and contextual information. You can look inside any |
||||
application by either navigating inside it from the commandline or by |
||||
right-clicking on it in Finder and choosing “Show Package Contents.”</p> |
||||
|
||||
<p>The basic layout is:</p> |
||||
|
||||
<pre>Pd-0.47-1.app/Contents |
||||
Info.plist <- contextual info: version string, get info string, etc |
||||
/Frameworks <- embedded Tcl/Tk frameworks (optional) |
||||
/MacOS/Pd <- renamed Wish bundle launcher |
||||
/Resources |
||||
/bin <- pd binaries |
||||
/doc <- built in docs & help files |
||||
/extra <- core externals |
||||
/font <- included fonts |
||||
/po <- text translation files |
||||
/src <- Pd source header files |
||||
/tcl <- Pd GUI scripts</pre> |
||||
|
||||
<p>The Pure Data GUI utilizes the Tk windowing shell aka “Wish” at runtime. |
||||
Creating a Pure Data .app involves using a precompiled Wish.app as a wrapper |
||||
by copying the Pd binaries and resources inside of it.</p> |
||||
|
||||
<h3 id="App.Bundle.Helpers">App Bundle Helpers</h3> |
||||
|
||||
<ul> |
||||
<li>osx-app.sh: creates a Pd .app bundle for macOS using a Tk Wish.app wrapper</li> |
||||
<li>tcltk-wish.sh: downloads and builds a Tcl/Tk Wish.app for macOS</li> |
||||
</ul> |
||||
|
||||
|
||||
<p>These scripts complement the autotools build system described in INSTALL.txt and |
||||
are meant to be run after Pd is configured and built. The following usage, for |
||||
example, downloads and builds a 32 bit Tk 8.6.6 Wish.app which is used to create |
||||
a macOS Pd-0.47-1.app:</p> |
||||
|
||||
<pre>mac/tcltk-wish.sh --arch i386 8.6.6 |
||||
mac/osx-app.sh --wish Wish-8.6.6.app 0.47-1 |
||||
</pre> |
||||
|
||||
<p>Both osx-app.sh & tcltck-wish.sh have extensive help output using the –help |
||||
commandline option:</p> |
||||
|
||||
<pre>mac/osx-app.sh --help |
||||
mac/tcltk-wish.sh --help |
||||
</pre> |
||||
|
||||
<p>The osx-app.sh script automates building the Pd .app bundle and is used in the |
||||
“make app” makefile target. This default action can be invoked manually after |
||||
Pd is built:</p> |
||||
|
||||
<pre>mac/osx-app.sh 0.47-1 |
||||
</pre> |
||||
|
||||
<p>This builds a “Pd-0.47-1.app” using the included Wish. If you omit the version |
||||
argument, a “Pd.app” is built. The version argument is only used as a suffix to |
||||
the file name and contextual version info is pulled from configure script |
||||
output.</p> |
||||
|
||||
<p>A pre-built universal (32/64 bit) Tk 8.6.10 Wish with patches applied is |
||||
included with the Pd source distribution and works across the majority of macOS |
||||
versions up to 10.15. This is the default Wish.app when using osx-app.sh. If you |
||||
want to use a different Wish.app (a newer version, a custom build, a system |
||||
version), you can specify the donor via commandline options, for example:</p> |
||||
|
||||
<pre># build Pd-0.47-1.app using Tk 8.6 installed to the system |
||||
mac/osx-app.sh --system-tk 8.6 0.47-1 |
||||
</pre> |
||||
|
||||
<p>If you want Pd to use a newer version of Tcl/Tk, but do not want to install to |
||||
it to your system, you can build Tcl/Tk as embedded frameworks inside of the Pd |
||||
.app bundle. This has the advantage of portability to other systems.</p> |
||||
|
||||
<p>The tcltk-wish.sh script automates building a Wish.app with embedded Tcl/Tk, |
||||
either from the release distributions or from a git clone:</p> |
||||
|
||||
<pre># build Wish-8.6.6.app with embedded Tcl/Tk 8.6.6 |
||||
mac/tcltk-wish.sh 8.6.6 |
||||
|
||||
# build Wish-master-git.app from the latest Tcl/Tk master branch from git |
||||
mac/tcltk-wish.sh --git master-git |
||||
</pre> |
||||
|
||||
<p>You can also specify which architectures to build (32 bit, 64 bit, or both):</p> |
||||
|
||||
<pre># build 32 bit Wish-8.6.6.app with embedded Tcl/Tk 8.6.6 |
||||
mac/tcltk-wish.sh --arch i386 8.6.6 |
||||
|
||||
# build universal (32 & 64 bit) |
||||
mac/tcltk-wish.sh --universal 8.6.6 |
||||
</pre> |
||||
|
||||
<p>Once your custom Wish.app is built, you can use it as the .app source for |
||||
osx-app.sh with the -w/–wish option:</p> |
||||
|
||||
<pre># build Pd with a custom Tcl/Tk 8.6.6 Wish |
||||
mac/osx-app.sh -w Wish-8.6.6.app |
||||
</pre> |
||||
|
||||
<p>Downloading and building Tcl/Tk takes some time. If you are doing lots of builds |
||||
of Pd and/or are experimenting with different versions of Tcl/Tk, building the |
||||
embedded Wish.apps you need with tcltk-wish.sh can save you some time as they |
||||
can be reused when (re)making the Pd .app bundle.</p> |
||||
|
||||
<p>Usually, it’s best to use stable releases of Tcl/Tk. However, there are times |
||||
when building from the current development version is useful. For instance, |
||||
if there is a bug in the Tcl/Tk sources and the generated Wish.app crashes on |
||||
your system, you can then see if there is a fix for this in the Tcl/Tk |
||||
development version on GitHub. If so, then you can test by using the |
||||
tcltk-wish.sh –git commandline option. Oftentimes, these kinds of issues will |
||||
appear with a newer version of macOS before they have been fixed by the open |
||||
source community.</p> |
||||
|
||||
<p>Additionally, Pd uses an older version of Tcl/Tk for backwards compatibility on |
||||
macOS. As such, small bugfixes from newer versions may need to be backported for |
||||
the Pd GUI. Currently, this is handled in the tcltk-wish.sh script by applying |
||||
custom patches to either the Tcl and/or Tk source trees. To skip applying |
||||
patches, use the tcltk-wish.sh –no-patches commandline option. See |
||||
mac/patches/README.txt for more info.</p> |
||||
|
||||
<h3 id="Supplementary.Build.Scripts">Supplementary Build Scripts</h3> |
||||
|
||||
<ul> |
||||
<li>build-macosx: builds a 32 bit Pd .app bundle using src/makefile.mac</li> |
||||
<li>build-mac64: builds a 64 bit Pd .app bundle using src/makefile.mac</li> |
||||
</ul> |
||||
|
||||
|
||||
<p>These scripts automate building Pd with the fallback makefiles in the src |
||||
directory.</p> |
||||
|
||||
<p>To build a 32 bit Pd, copy this “mac” directory somewhere like ~/mac. Also copy |
||||
a source tarball there, such as pd-0.47-1.src.tar.gz. Then cd to ~/mac and type:</p> |
||||
|
||||
<pre>./build-macosx 0.47-1 |
||||
</pre> |
||||
|
||||
<p>If all goes well, you’ll soon see a new app appear named Pd-0.47-1.app.</p> |
||||
|
||||
<p>If you want to build a 64 bit Pd, perform the same steps and use the build-mac64 |
||||
script:</p> |
||||
|
||||
<pre>./build-mac64 0.47-1 |
||||
</pre> |
||||
|
||||
<p>Note: The “wish-shell.tgz” is an archive of this app I found on my mac: |
||||
/System/Library/Frameworks/Tk.framework/Versions/8.4/Resources/Wish Shell.app</p> |
||||
|
||||
<p>A smarter version of the scripts ought to be able to find that file |
||||
automatically on your system so I wouldn’t have to include it here.</p> |
||||
|
||||
<h3 id="Preferences">Preferences</h3> |
||||
|
||||
<p>The Pure Data preferences are saved in the macOS “defaults” preference system |
||||
using the following domains:</p> |
||||
|
||||
<ul> |
||||
<li>org.puredata.pd: core settings (audio devices, search paths, etc)</li> |
||||
<li>org.puredata.pd.pd-gui: GUI settings (recent files, last opened location, etc)</li> |
||||
</ul> |
||||
|
||||
|
||||
<p>The files themselves live in your user home folder and use the .plist extension:</p> |
||||
|
||||
<pre>~/Library/Preferences/org.puredata.pd.plist |
||||
~/Library/Preferences/org.puredata.pd.pd-gui.plist |
||||
</pre> |
||||
|
||||
<p>These files use the Apple Property List XML format and shouldn’t be edited |
||||
directly. You can look inside, edit, and/or delete these using the “defaults” |
||||
commandline utility in Terminal:</p> |
||||
|
||||
<pre># print the contents of the core settings |
||||
defaults read org.puredata.pd |
||||
|
||||
# delete the current GUI settings |
||||
defaults delete org.puredata.pd.pd-gui |
||||
|
||||
# set the startup flag in the core settings |
||||
defaults write org.puredata.pd -array-add flags '-lib Gem' |
||||
</pre> |
||||
|
||||
<p>Some important per-application settings required by the GUI include:</p> |
||||
|
||||
<ul> |
||||
<li>NSRecentDocuments: string array, list of recently opened files</li> |
||||
<li>NSQuitAlwaysKeepsWindows: false, disables default 10.7+ window state saving</li> |
||||
<li>ApplePressAndHoldEnabled: false, disables character compose popup, |
||||
enables key repeat for all keys</li> |
||||
</ul> |
||||
|
||||
|
||||
<p>These are set in tcl/pd_guiprefs.tcl.</p> |
||||
|
||||
<h3 id="Code.Signing">Code Signing</h3> |
||||
|
||||
<p>As of Pd 0.51, the mac/osx-app.sh script performs “ad-hoc code signing” in order |
||||
to set entitlements to open un-validated dynamic libraries on macOS 10.15+. This |
||||
is required due to the new security settings. Note: ad-hoc signing doesn’t |
||||
actually sign the .app bundle with an account certificate, so the unidentified |
||||
developer warning is still shown when the downloaded .app is run for the first |
||||
time.</p> |
||||
</br> |
||||
|
||||
<p><a class=green href="x6.htm#more-mac" >back to ch6</a> <a href="index.htm#s6"> back to table of contents </a></p> |
||||
</br> |
||||
</br> |
||||
</br> |
||||
|
||||
</div> |
||||
|
||||
|
||||
</BODY> |
||||
</HTML> |
||||
@ -0,0 +1,205 @@ |
||||
<!DOCTYPE html> |
||||
|
||||
<HTML lang="en"> |
||||
<HEAD> |
||||
<meta charset="UTF-8"> |
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
||||
<TITLE>Pd Manual 6</TITLE> |
||||
<meta http-equiv="Content-Type" content="text/html"> |
||||
<link rel="stylesheet" type="text/css" href="pdmanual.css" media="screen"> |
||||
<link rel="icon" type="image/png" href="favicon.ico"> |
||||
</HEAD> |
||||
|
||||
<BODY> |
||||
|
||||
|
||||
<div class="butt"> |
||||
|
||||
</div> |
||||
|
||||
<div id=corpus> |
||||
|
||||
<p><a class=green href="x6.htm#more-windows" >back to ch6</a> <a href="index.htm#s6"> back to table of contents </a></p> |
||||
|
||||
<h3 id="s6.5.1">6.5.1 Windows resources</h3> |
||||
|
||||
<p>Directory pure-data/msw contains support files for building a Pure Data Windows |
||||
application, as it is built for the ‘vanilla’ releases on msp.ucsd.edu.</p> |
||||
|
||||
<h3 id="Notes.about.compiling.on.Microsoft.Windows">Notes about compiling on Microsoft Windows</h3> |
||||
|
||||
<p>As of Pd version 0.50, all releases are compiled using Dan Wilcox’s scripts, |
||||
msw-app.sh, and optionally tcltk-dir.sh (which builds a version of TCL/TK in |
||||
case you don’t already have one).</p> |
||||
|
||||
<p>The Pd sources aren’t completely self-contained: Because of licensing |
||||
restrictions, the ASIO support files are not included in the Pd source tree. |
||||
The msw-app.sh script presumes you’ve downloaded the ASIO SDK and can point |
||||
msw-app.sh to it.</p> |
||||
|
||||
<p>It’s also possible to compile Pd using Visual C. This is not managed |
||||
automatically but you can look in “how-to-use-msvc.sh” to see how it can be |
||||
done. This compiler gives different warnings which are sometimes useful, and |
||||
refuses to compile code that has variable declarations in the middle of a |
||||
block. It’s a good idea to test pull requests against MSVC if you can. The |
||||
file “pdprototype.zip” contains all the garbage that Pd needs in addition to its |
||||
own files, including tcl/tk. MSVC compilation works in 32 bits only.</p> |
||||
|
||||
<p>The scripts build-msw-32.sh and build-msw-64.sh are the ones used by Miller to |
||||
make Pd releases. These files work on Linux only and will not work out of |
||||
the box unless your file tree resembles Miller’s in some ways (pd source is in |
||||
~/pd for instance) but you can presumably make your own version if you need to.</p> |
||||
|
||||
<p>But to first get things working, it’s best to use msw-app.sh and tcltk-dir.sh |
||||
directly.</p> |
||||
|
||||
<h3 id="Pd.Application.Directory">Pd Application Directory</h3> |
||||
|
||||
<p>Pd for Windows is essentially a stand-alone application directory which contains |
||||
the compiled binaries, resource files, and contextual information.</p> |
||||
|
||||
<p>The basic layout is:</p> |
||||
|
||||
<pre>pd |
||||
/bin <- pd binaries |
||||
/doc <- built in docs & help files |
||||
/extra <- core externals |
||||
/font <- included fonts |
||||
/lib <- embedded Tcl/Tk frameworks |
||||
/po <- text translation files |
||||
/src <- Pd source header files |
||||
/tcl <- Pd GUI scripts</pre> |
||||
|
||||
<p>The Pure Data GUI utilizes the Tk windowing shell aka “wish##.exe” at runtime |
||||
which is included with Pd in the /bin directory. A Pure Data app directory |
||||
includes both the Pd binaries and resources as well as a precompiled Tk.</p> |
||||
|
||||
<h3 id="App.Bundle.Helpers">App Bundle Helpers</h3> |
||||
|
||||
<ul> |
||||
<li>msw-app.sh: creates a Pd app directory for Windows using precompiled Tcl/Tk</li> |
||||
<li>tcltk-dir.sh: downloads and builds Tcl/Tk for Windows</li> |
||||
</ul> |
||||
|
||||
|
||||
<p>These scripts complement the autotools build system described in INSTALL.txt and |
||||
are meant to be run after Pd is configured and built. The following usage, for |
||||
example, downloads and builds 32 bit Tk 8.6.8 which is used to create |
||||
a Windows pd-0.48-1 directory:</p> |
||||
|
||||
<pre>msw/tcltk-dir.sh 8.6.8 |
||||
msw/msw-app.sh --tk tcltk-8.6.8 0.48-1 |
||||
</pre> |
||||
|
||||
<p>Both msw-app.sh & tcltck-dir.sh have extensive help output using the –help |
||||
commandline option:</p> |
||||
|
||||
<pre>msw/msw-app.sh --help |
||||
msw/tcltk-dir.sh --help |
||||
</pre> |
||||
|
||||
<p>The msw-app.sh script automates building the Pd app directory and is used in the |
||||
“make app” makefile target. This default action can be invoked manually after |
||||
Pd is built:</p> |
||||
|
||||
<pre>msw/msw-app.sh 0.47-1 |
||||
</pre> |
||||
|
||||
<p>This builds a “pd-0.47-1” directory using the default copy of Tk. If you omit |
||||
the version argument, a “pd” directory is built. The version argument is only |
||||
used as a suffix to the directory name.</p> |
||||
|
||||
<p>The “msw/pdprototype.tgz” archive contains the basic requirements for running Pd |
||||
on Windows: a precompiled copy of Tcl/Tk and various .dll library files. This is |
||||
the default Tcl/Tk when using msw-app.</p> |
||||
|
||||
<p>If you want to use a newer Tcl/Tk version or a custom build, you can specify the |
||||
version or directory via commandline options, for example:</p> |
||||
|
||||
<pre># create pd-0.48-1 directory, download and build Tcl/Tk 8.5.19 |
||||
msw/msw-app.sh --tk 8.5.19 0.48-1 |
||||
|
||||
# create pd-0.48-1 directory, use Tcl/Tk 8.5.19 built with tcltk-dir.sh |
||||
msw/msw-app.sh --tk tcltk-8.5.19 0.48-1 |
||||
</pre> |
||||
|
||||
<p>Note: Depending on which version of Tcl/Tk you want to use, you may need to set |
||||
the Tk Wish command when configuring Pd. To build Pd to use Tk 8.6:</p> |
||||
|
||||
<pre>./configure --with-wish=wish86.exe |
||||
make |
||||
</pre> |
||||
|
||||
<p>The tcltk-dir.sh script automates building Tcl/Tk for Windows, either from the |
||||
release distributions or from a git clone:</p> |
||||
|
||||
<pre># build tcltk-8.5.19 directory with Tcl/Tk 8.5.19 |
||||
msw/tcltk-dir.sh 8.5.19 |
||||
|
||||
# build tcltk-master-git with the latest master branch from git |
||||
msw/tcltk-dir.sh --git master-git |
||||
</pre> |
||||
|
||||
<p>Once your custom Tcl/Tk is built, you can use it as the Tk directory source for |
||||
msw-app.sh with the -t/–tk option:</p> |
||||
|
||||
<pre># build Pd with a custom Tcl/Tk 8.6.8 directory |
||||
msw/msw-app.sh -t tcltk-8.6.8 |
||||
</pre> |
||||
|
||||
<p>Downloading and building Tcl/Tk takes some time. If you are doing lots of builds |
||||
of Pd and/or are experimenting with different versions of Tcl/Tk, building the |
||||
tcltk directories you need with tcltk-dir.sh can save you some time as they |
||||
can be reused when (re)making the Pd app directory.</p> |
||||
|
||||
<p>Usually, it’s best to use stable releases of Tcl/Tk. However, there are times |
||||
when building from the current development version is useful. For instance, |
||||
if there is a bug in the Tcl/Tk sources, you can then see if there is a fix for |
||||
this in the Tcl/Tk development version on GitHub. If so, then you can test by |
||||
using the tcltk-dir.sh –git commandline option.</p> |
||||
|
||||
<p>The tcltk-dir.sh script tries to detect if it’s building in a 64 bit |
||||
environment, ie. MinGW 64. If this detection fails, you can force 64 bit with |
||||
the –64bit option:</p> |
||||
|
||||
<pre># force 64 bit Tcl/Tk 8.6.8 build |
||||
tcltk-dir.sh --64bit 8.6.8 |
||||
</pre> |
||||
|
||||
<h3 id="pdfontloader">pdfontloader</h3> |
||||
|
||||
<p>Tk cannot load local font files by default on Windows. Pd accomplishes this |
||||
through a tiny, custom Tcl extension, pdfontloader.dll. On initialization, the |
||||
Pd GUI tries to load pdfontloader and, if successful, tries to load the included |
||||
Pd font.</p> |
||||
|
||||
<p>Currently, pdfontloader.dll is pre-built and included within the pdprototype.tgz |
||||
tarball. To build pdfontloader, see <a href="https://github.com/pure-data/pdfontloader" target="_blank">https://github.com/pure-data/pdfontloader</a> |
||||
source.</p> |
||||
|
||||
<h3 id="s6.5.2">6.5.2. Windows ASIO Support</h3> |
||||
|
||||
<p>In order to build ASIO support into Pd on Windows, you need to download the |
||||
ASIO sources from Steinberg directly. Their license does not let us |
||||
redistribute their source files.</p> |
||||
|
||||
<p>Install the ASIO SDK by doing the following:</p> |
||||
|
||||
<ul> |
||||
<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> |
||||
<li>2. Uncompress asiosdk2.3.zip (or higher) into pure-data/asio/</li> |
||||
<li>3. remove the version number so that you get pure-data/asio/ASIOSDK</li> |
||||
</ul> |
||||
|
||||
<p>Now build Pd and it should include ASIO as one of the audio backends.</p> |
||||
|
||||
</br> |
||||
<p><a class=green href="x6.htm#more-windows" >back to ch6</a> <a href="index.htm#s6"> back to table of contents </a></p> |
||||
</br> |
||||
</br> |
||||
</br> |
||||
|
||||
</div> |
||||
|
||||
</BODY> |
||||
</HTML> |
||||
@ -0,0 +1,459 @@ |
||||
<!DOCTYPE html> |
||||
|
||||
<HTML lang="en"> |
||||
<HEAD> |
||||
<meta charset="UTF-8"> |
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0"> |
||||
<TITLE>Pd Manual 6</TITLE> |
||||
<meta http-equiv="Content-Type" content="text/html"> |
||||
<link rel="stylesheet" type="text/css" href="pdmanual.css" media="screen"> |
||||
<link rel="icon" type="image/png" href="favicon.ico"> |
||||
</HEAD> |
||||
|
||||
<BODY> |
||||
|
||||
|
||||
<div class="butt"> |
||||
|
||||
</div> |
||||
|
||||
<div id=corpus> |
||||
|
||||
|
||||
|
||||
<H2>Pd Manual chapter 6: Installing from source.</H2> |
||||
|
||||
<P> |
||||
<A href="index.htm#s6"> back to table of contents </A> |
||||
<BR><BR> |
||||
</P> |
||||
|
||||
<P>Pd is built on the commandline using traditional Unix-style tools. The source |
||||
distribution comes with two build systems:</P> |
||||
|
||||
<ul> |
||||
<li>autotools: easy to use, many compilation options, recommended for most users</li> |
||||
<li>makefile: smaller & simpler, used for Pd binary downloads</li> |
||||
</ul> |
||||
|
||||
<h3 id="s6.1">6.1. Requirements</h3> |
||||
|
||||
<p>Core build requirements:</p> |
||||
|
||||
<ul> |
||||
<li>Unix command shell: bash, dash, etc</li> |
||||
<li>C compiler chain: gcc/clang & make</li> |
||||
</ul> |
||||
|
||||
<p>Core runtime requirements:</p> |
||||
|
||||
<ul> |
||||
<li>Tcl/Tk: Tk wish shell</li> |
||||
</ul> |
||||
|
||||
<p>Optional features:</p> |
||||
|
||||
<ul> |
||||
<li>autotools: autoconf, automake, & libtool (if building with the autotools)</li> |
||||
<li>gettext: build localizations in the po directory</li> |
||||
<li>JACK: audio server support</li> |
||||
<li>FFTW: use the optimized FFTW Fast Fourier Transform library</li> |
||||
</ul> |
||||
|
||||
<h3 id="s6.2">6.2. Autotools Build (recommended)</h3> |
||||
|
||||
<p>Building Pd using the GNU autotools involves the following steps for all platforms:</p> |
||||
|
||||
<ul> |
||||
<li>1. configure: detect & set library and platform options</li> |
||||
<li>2. make: compile Pd, associated tools, and resource files (ie. translations)</li> |
||||
<li>3. install: install the Pd binaries and resources onto your system</li> |
||||
</ul> |
||||
|
||||
<p>Overview:</p> |
||||
|
||||
<pre>cd path/to/pd |
||||
./autogen.sh |
||||
./configure |
||||
make |
||||
</pre> |
||||
|
||||
<p>Note: Additional platform-specific options and build targets are listed in following subsections.</p> |
||||
<p>Start by opening a commandline shell and navigating to the Pd source directory:</p> |
||||
|
||||
<pre>cd path/to/pd</pre> |
||||
|
||||
<p>First generate the configure script and various build files by running:</p> |
||||
|
||||
<pre>./autogen.sh</pre> |
||||
|
||||
<p>Next configure Pd with the default options for your platform:</p> |
||||
|
||||
<pre>./configure</pre> |
||||
|
||||
<p>You can verify the configuration options that the configure step script prints:</p> |
||||
|
||||
<pre>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</pre> |
||||
|
||||
<p>If you want to change these options, you can specify/override the configure script settings on the commandline:</p> |
||||
|
||||
<pre># 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</pre> |
||||
|
||||
<p>An important configure option for some platforms is --enable-universal 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 --enable-universal:</p> |
||||
|
||||
<pre># build 32 bit Pd |
||||
./configure --enable-universal=i386 |
||||
|
||||
# build 64 bit Pd |
||||
./configure --with-universal=x86_64</pre> |
||||
|
||||
<p>The full list of available configuration options can printed by running:</p> |
||||
|
||||
<pre>./configure --help</pre> |
||||
|
||||
<p>Now that Pd is configured, build by running:</p> |
||||
|
||||
<pre>make</pre> |
||||
|
||||
<p>Building should take a minute or two. If compilation was successful, you can run Pd from the build directory without installing it:</p> |
||||
|
||||
<pre>cd bin |
||||
./pd</pre> |
||||
|
||||
<p>To install to your system using the configuration prefix (default /usr/local):</p> |
||||
|
||||
<pre>sudo make install</pre> |
||||
|
||||
<p>You can also to a custom location via:</p> |
||||
|
||||
<pre>make install DESTDIR=~/pd-xxx prefix=/</pre> |
||||
|
||||
<p>Once installed, you should now be able to run Pd from the commandline:</p> |
||||
|
||||
<pre>pd</pre> |
||||
|
||||
<p>If want to uninstall, make sure Pd is configured and then run:</p> |
||||
|
||||
<pre>sudo make uninstall</pre> |
||||
|
||||
<p>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:</p> |
||||
|
||||
<pre># 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</pre> |
||||
|
||||
<h3 id="s6.3">6.3 Linux & BSD</h3> |
||||
|
||||
<p>Platform requirements:</p> |
||||
|
||||
<ul> |
||||
<li>ALSA: Linux sound library (recommended)</li> |
||||
<li>OSS: historical precursor to ALSA, generally not used</li> |
||||
<li>JACK: JACK audio server (optional)</li> |
||||
</ul> |
||||
|
||||
<p>Install the core build requirements using your distribution's package manager. For Debian, you can install the compiler chain, autotools, & gettext with:</p> |
||||
|
||||
<pre>sudo apt-get install build-essential automake autoconf libtool gettext</pre> |
||||
|
||||
<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> |
||||
|
||||
<pre>sudo apt-get install libasound2-dev</pre> |
||||
|
||||
<p>Similarly, optional development libraries can be also be installed to for additional features. Install the JACK development files on Debian:</p> |
||||
|
||||
<pre>sudo apt-get install libjack-jackd2-dev</pre> |
||||
|
||||
<p>In case you are using jackd1 instead of jackd2, use:</p> |
||||
|
||||
<pre>sudo apt-get install libjack-dev</pre> |
||||
|
||||
<p>Most distributions come with Tcl/Tk installed, so you should be able to run Pd after it is built.</p> |
||||
<p>Once your build system is set up, you can follow the general autotools build steps to build Pd.</p> |
||||
|
||||
<h3 id="s6.4">6.4. macOS</h3> |
||||
|
||||
<p>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.</p> |
||||
<p>The clang compiler and associated tools are provided by Apple. If you are running macOS 10.9+, you <em>do not</em> need to install the full Xcode application and can install the Commandline Tools Package only by running the following:</p> |
||||
|
||||
<pre>xcode-select --install</pre> |
||||
|
||||
<p>If you are running macOS 10.6 - 10.8, you will need to install Xcode from the Mac App Store or downloaded from <a href="http://developer.apple.com" target="_blank">http://developer.apple.com</a></p> |
||||
<p>Tcl/Tk is already included macOS.</p> |
||||
<p>To install the autotools, gettext, and libraries for additional features, you can use one of the open source package managers for macOS:</p> |
||||
|
||||
<ul> |
||||
<li>homebrew: <a href="https://brew.sh" target="_blank">https://brew.sh </a>(recommended)</li> |
||||
<li>macports: <a href="https://www.macports.org" target="_blank">https://www.macports.org</a></li> |
||||
</ul> |
||||
|
||||
<p>Follow the package manager set up instructions and then install the software you need. For example, to install the autotools & gettext using Homebrew:</p> |
||||
|
||||
<pre>brew install automake autoconf libtool pkg-config gettext |
||||
brew link --force gettext</pre> |
||||
|
||||
<p>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 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: 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 a "fat" Pd for all architectures supported by the compiler:</p> |
||||
|
||||
<ul> |
||||
<li>macOS 10.6: i386, x86_64, ppc</li> |
||||
<li>macOS 10.7+: i386, x86_64</li> |
||||
<li>macOS 10.15: x86_64</li> |
||||
</ul> |
||||
|
||||
<p>Note: a "fat" Pd may not work on all systems and/or be able to load both 32 or 64 bit externals. Additionally, you can specify multiple architectures directly:</p> |
||||
|
||||
<pre># build a "fat" Pd for both 32 and 64 bit |
||||
# may not work on all systems |
||||
./configure --enable-universal=i386,x86_64 |
||||
|
||||
# build a "fat" Pd for all detected architectures (macOS: i386, x86_64, ppc) |
||||
# may not work on all systems |
||||
./configure --enable-universal</pre> |
||||
|
||||
<p>The JACK audio server is supported by Pd on macOS. By default, Pd can use the Jack OS X runtime framework from <a href="http://www.jackosx.com" target="_blank">http://www.jackosx.com</a> 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:</p> |
||||
|
||||
<pre>brew install jack |
||||
./configure --disable-jack-framework --enable-jack</pre> |
||||
|
||||
<p>You should now be ready to build Pd by following the general autotools build steps. Once built, there are two options for installation:</p> |
||||
|
||||
<ul> |
||||
<li>build a standalone macOS application (recommended)</li> |
||||
<li>install to your system as a commandline program</li> |
||||
</ul> |
||||
|
||||
<p>To build the Pd macOS application, simply run:</p> |
||||
|
||||
<pre>make app</pre> |
||||
|
||||
<p>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 <a href="x6-a.htm">6.4.1 macOS resources</a>.</p> |
||||
<p>If you want to have both the Pd application <em>and</em> use Pd from the commandline, add command aliases to the binaries inside the .app to your ~/.bash_profile:</p> |
||||
|
||||
<h4 id="pd-commandline">pd commandline</h4> |
||||
|
||||
<p>WHICHPD="Pd-0.47-1" alias pd="/Applications/<span class="math">$WHICHPD.app/Contents/Resources/bin/pd" alias pdsend="/Applications/$</span>WHICHPD.app/Contents/Resources/bin/pdsend" alias pdreceive="/Applications/$WHICHPD.app/Contents/Resources/bin/pdreceive"</p> |
||||
|
||||
<p>Next, reload the profile by either opening a new Terminal window or running:</p> |
||||
|
||||
<pre>source ~/.bash_profile</pre> |
||||
|
||||
<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> |
||||
|
||||
<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> |
||||
|
||||
<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 "/usr/bin/wish8.4". You can configure Pd to use this search path first with:</p> |
||||
|
||||
<pre>./configure --with-wish=/usr/bin/wish8.4</pre> |
||||
|
||||
<p>To see Pd's path search info, run Pd with the -verbose flag:</p> |
||||
|
||||
<pre>pd -verbose</pre> |
||||
|
||||
<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> |
||||
|
||||
<p><a id=more-mac class=green href="x6-a.htm" >Show more on macOS</a></p> |
||||
|
||||
<h3 id="s6.5">6.5. Windows</h3> |
||||
|
||||
<p>Pd on Windows can be built with either MinGW or Cygwin which provide the core build requirements: a compiler chain & shell environment.</p> |
||||
<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> |
||||
|
||||
<p><a href="http://www.msys2.org/" target="_blank">http://www.msys2.org/</a></p> |
||||
|
||||
<p>Then install to the default location (C:32 or C:64) and follow the setup/update info on the Msys2 webpage.</p> |
||||
<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 --enable-universal build option has no effect in MinGW.</p> |
||||
<p>Note: Msys2 development seems to change frequently, so some of the package names below may have changed after this document was written.</p> |
||||
<p>Open an Msys2 shell and install the compiler chain, autotools, & gettext via:</p> |
||||
|
||||
<pre># 64 bit |
||||
pacman -S mingw-w64-x86_64-toolchain mingw-w64-x86_64-clang \ |
||||
make autoconf automake libtool \ |
||||
mingw-w64-x86_64-gettext |
||||
|
||||
# 32 bit |
||||
pacman -S mingw-w64-i686-toolchain mingw-w64-i686-clang \ |
||||
make autoconf automake libtool \ |
||||
mingw-w64-i686-gettext</pre> |
||||
|
||||
<p>Install git if you want to clone the Pd sources from Github, etc:</p> |
||||
|
||||
<pre>pacman -S git</pre> |
||||
|
||||
<p>and/or the nsis installer tool if you want to build the Pd Windows installer:</p> |
||||
|
||||
<pre># 64 bit |
||||
pacman -S mingw-w64-x86_64-nsis |
||||
|
||||
# 32 bit |
||||
pacman -S mingw-w64-i686-nsis</pre> |
||||
|
||||
<p>Note: You can also search for packages in Msys2 with:</p> |
||||
|
||||
<pre>pacman -S -s <searchterm></pre> |
||||
|
||||
<p>Once the packages are installed, you should now be ready to build Pd by following the general autotools build steps.</p> |
||||
<p>The following audio APIS are available on Windows and can be enabled/disabled via their configure flags:</p> |
||||
|
||||
<ul> |
||||
<li>MMIO: --enable-mmio or --disable-mmio (default enabled)</li> |
||||
<li>ASIO: --enable-asio or --disable-asio (default enabled, if found)</li> |
||||
<li>JACK: --enable-jack or --disable-jack</li> |
||||
</ul> |
||||
|
||||
<p>For example, to build Pd without MMIO support:</p> |
||||
|
||||
<pre>./configure --disable-mmio</pre> |
||||
|
||||
<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="x6-b.htm#s6.5.2">6.5.2 Windows ASIO Support </a> for further instructions.</p> |
||||
<p>Once built Pd is built, you can either:</p> |
||||
|
||||
<ul> |
||||
<li>build a Pd application directory for Windows (recommended)</li> |
||||
<li>build a Windows installer</li> |
||||
</ul> |
||||
|
||||
<p>A Pd application directory is essentially a self-contained Pd package which should run out of the box. To build, simply use:</p> |
||||
|
||||
<pre>make app</pre> |
||||
|
||||
<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. For more info & options regarding the Pd app directory, see <a href="x6-b.htm">6.5.1 Windows resources.</a> </p> |
||||
<p>To build a .msi Windows installer for Pd, see msw/build-nsi.sh.</p> |
||||
<p>Note: The standard "make install" requires Tcl/Tk and won't work outside your Cygwin/Msys2 environment (if at all).</p> |
||||
|
||||
<p><a id=more-windows class=green href="x6-b.htm" >Show more on Windows</a></p> |
||||
|
||||
<h3 id="s6.6">6.6. Double precision</h3> |
||||
|
||||
<p>As of Pd 0.51-0 you can compile a "Double precision" Pd. On the autotools do:</p> |
||||
|
||||
<pre>./configure CPPFLAGS="-DPD_FLOATSIZE=64"</pre> |
||||
|
||||
<h3 id="s6.7">6.7. Other flags</h3> |
||||
|
||||
<p>More flags to be documented here.</p> |
||||
|
||||
<h3 id="s6.8">6.8. Cross-compilation for Windows on Linux</h3> |
||||
|
||||
<p>You can also build a Windows binary of Pd on a Linux system, using a cross-compilation toolchain.</p> |
||||
<p>For Debian based systems (e.g. Ubuntu), you can install the toolchain with:</p> |
||||
|
||||
<pre>sudo apt-get install build-essential automake autoconf libtool gettext |
||||
sudo apt-get install mingw-w64 mingw-w64-tools |
||||
sudo apt-get install nsis</pre> |
||||
|
||||
<p>The "mingw-w64" package will install the cross compilation toolchains for both 32bit (g++-mingw-w64-i686, binutils-mingw-w64-i686) and 64bit (g++-mingw-w64-x86-64, binutils-mingw-w64-x86-64).</p> |
||||
<p>The "nsis" package is purely optional, and only needed if you want to build the installer.</p> |
||||
<p>You must tell configure that you want to cross-compile for a given architecture via the "--host" configure flag.</p> |
||||
<p>For example, to build a 32 bit Pd:</p> |
||||
|
||||
<pre>./configure --host=i686-w64-mingw32</pre> |
||||
|
||||
<p>Similarly, to build a 64 bit Pd without ASIO support:</p> |
||||
|
||||
<pre>./configure --disable-asio --host=x86_64-w64-mingw32</pre> |
||||
|
||||
<p>If all went well, you should now be ready to build Pd, as explained in the instructions above in the "Windows" section:</p> |
||||
|
||||
<pre>make app</pre> |
||||
|
||||
<h3 id="s6.9">6.9. Makefile Build</h3> |
||||
|
||||
<p>Alternatively, and often more simply, to the autotools build, you can use the fallback makefiles in the src directory:</p> |
||||
|
||||
<ul> |
||||
<li>src/makefile.gnu: GNU/Linux</li> |
||||
<li>src/makefile.mac: macOS</li> |
||||
<li>src/makefile.msvc: Windows with Microsoft Visual C</li> |
||||
<li>src/makefile.mingw: Windows with MinGW GCC</li> |
||||
</ul> |
||||
|
||||
<p>On Linux, for example, run the GNU-specific makefile in the src directory:</p> |
||||
|
||||
<pre>cd src |
||||
make -f makefile.gnu</pre> |
||||
|
||||
<p>You can then run directly out of the bin directory without installing:</p> |
||||
|
||||
<pre>cd ../bin |
||||
./pd</pre> |
||||
|
||||
<p>For Microsoft Visual C, first build Pd with the MS VC makefile and then build each external in the extra directory:</p> |
||||
|
||||
<pre>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 |
||||
...</pre> |
||||
|
||||
<p>To install Pd to your system on Linux, macOS, & MinGW (Windows), use the "install" makefile target. For Linux, this is:</p> |
||||
|
||||
<pre>make -f makefile.gnu install</pre> |
||||
|
||||
<p>Once installed, you should now be able to run Pd from the commandline:</p> |
||||
|
||||
<pre>pd</pre> |
||||
|
||||
<p>If want to uninstall, simply run the "uninstall" makefile target:</p> |
||||
|
||||
<pre>make -f makefile.gnu uninstall</pre> |
||||
|
||||
<p>On macOS, you can build a clickable Pd .app bundle using the supplemental build scripts in the mac directory. See <a href="x6-a.htm">6.4.1 macOS resources</a>. for more info.</p> |
||||
|
||||
<h3 id="s6.10">6.10. Reporting Bugs</h3> |
||||
|
||||
<p>Let us know if you run into any bugs or issues with building or installing Pd:</p> |
||||
|
||||
<ul> |
||||
<li>send an email to the Pd-List: <a href="https://lists.puredata.info/listinfo/pd-list" target="_blank">https://lists.puredata.info/listinfo/pd-list</a></li> |
||||
<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> |
||||
<li>post to the Pd forum: <a href="https://forum.pdpatchrepo.info" target="_blank">https://forum.pdpatchrepo.info</a></li> |
||||
</ul> |
||||
|
||||
<p>Please include information involved with your problem such as:</p> |
||||
|
||||
<ul> |
||||
<li>information about your system: OS version, libraries installed, etc</li> |
||||
<li>configure or make output including error lines</li> |
||||
<li>steps you took: configuration options, etc</li> |
||||
</ul> |
||||
|
||||
|
||||
<P> |
||||
<BR><BR> |
||||
<A href="index.htm#s6"> back to table of contents </A> |
||||
<BR><BR> |
||||
</P> |
||||
|
||||
</div> |
||||
|
||||
|
||||
</BODY> |
||||
</HTML> |
||||
Loading…
Reference in new issue