Debian Codegraph @

doc/1.manual/4.externals.htm

raw
1 <!DOCTYPE html>
2 <HTML lang="en">
3 <HEAD>
4 <meta name="viewport" content="width=device-width, initial-scale=1.0">
5 <TITLE>Pd Manual - Chapter 4: Externals</TITLE>
6 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
7 <link rel="stylesheet" type="text/css" href="resources/pdmanual.css" media="screen">
8 <link rel="icon" href="resources/favicon.ico">
9 </HEAD>
10 <BODY>
11
12 <div class="nav nav-top">
13 <div class="nav-back"><A href="3.installing.configuring.htm">&lt; Chapter 3: Installing and configuring Pd</A></div>
14 <div class="nav-home"><A href="index.htm#s4">Table of contents</A></div>
15 <div class="nav-forward"><A href="5.current.status.htm">Chapter 5: Current status &gt;</A></div>
16 </div>
17 <div id=corpus>
18
19 <IMG id="logo" src="resources/icon.png" ALT="pd icon">
20
21 <H2>Chapter 4: Externals</H2>
22
23 <p> This chapter explains what are external objects and libraries. It also
24 describes everything on how to install and load them in Pure Data.</p>
25
26 <P>Pure Data, by intent and design, has a lightweight and portable nature.
27 Most likely you'll need or want to install externals to enhance Pd's
28 capabilities. Luckily, Pd offers a wide range of external packages by
29 third party developers that enhance its capabilities. Most of these are
30 primarily focused on audio and control processing, like "Ceammc", "Cyclone",
31 "ELSE", "FFTease", "Flucoma", "IEMlib", "Pmpd", "TimbreID", "Zexy", and
32 many more. The "vstplugin~" external allows you to run VST plugins inside Pd.
33 External libraries for graphical processing include Mark Dank's "GEM" and Zack
34 Lee's "Ofelia", which allows you to use openFrameworks and the Lua programming
35 language within Pd for creating audiovisual artwork or multimedia applications
36 such as games.</P>
37
38 <p> You can write your own external objects that you and others can use in
39 their Pd applications in C or (if you're smart and brave) in C++ or FORTRAN.
40 In the "6.externs" subdirectory of the 'doc' folder you can find simple
41 examples of externals with their source code and test patches. This is also
42 accessible via the browser window.</p>
43
44 <p>There’s also an excellent guide to writing externals at
45 <a href="https://github.com/pure-data/externals-howto">
46 https://github.com/pure-data/externals-howto</a>, written
47 by IOhannes zmölnig . Check also the pd-lib-builder project
48 (a helper makefile for Pure Data external libraries by Katja
49 Vetter) at <a href="http://github.com/pure-data/pd-lib-builder">
50 http://github.com/pure-data/pd-lib-builder</a>.</p>
51
52 <H3> <A href="#s4.1" id="s4.1"> 4.1 External Objects & Libraries </A> </H3>
53
54 <p> We start this section by defining what are internals and externals.
55 The main Pd distribution (a.k.a. “Pd Vanilla”) actually comes with both
56 internals and externals.</p>
57
58 <H4> <A href="#s4.1.1" id="s4.1.1"> 4.1.1 Vanilla objects, internals & externals </A> </H4>
59
60 <p> Internal objects come as part of the Pd binary, whereas external objects
61 are separate from it. Pd Vanilla also comes with a few “extra” objects that
62 are not part of its binary. Therefore, the set of “vanilla objects” (the
63 built-in objects in Pd) include internals and externals. Nonetheless,
64 “externals” mostly refer objects not available in the Pd Vanilla distribution,
65 that you need to download and install them properly so they can be loaded into
66 Pd patches. Some other flavors of Pd usually come with pre installed externals.</p>
67
68 <p> To get a full list of all objects in Pd Vanilla, go to the <b>Help menu</b> and
69 then select <b>List of Objects</b>, or alternatively right click on an empty spot of a
70 patch’s window and select “help” - this loads the help-intro.pd file that was already
71 shown in <a href="1.introduction.htm">Chapter 1: Introduction</a> and reproduced below.</p>
72
73 <figure>
74 <IMG src="resources/1.2.3.png" ALT="list of objects">
75 <figcaption><u>Fig. 1.2.3</u> The "help-intro' patch with a list of all internal objects</figcaption>
76 </figure>
77
78
79 <p> The set of externals that come with Pd Vanilla is available in the ‘extra’ library
80 and is located in a folder named “extra” inside the Pd application. These appear at the
81 very end of the “help-intro.pd” and can also be viewed in the "Browser" menu entry in
82 the <b>Help menu</b>. See figure below, which shows how the browser looks in a fresh
83 install of Pd and lists the objects in the extra folder.</p>
84
85 <figure>
86 <IMG src="resources/4.1.1.png" ALT="browser window">
87 <figcaption><u>Fig. 4.1.1</u> The browser window</figcaption>
88 </figure>
89
90 <H4> <A href="#s4.1.2" id="s4.1.2"> 4.1.2. Types of external objects </A> </H4>
91
92 <p> An object in Pd can be either a patch file (an abstraction) or a
93 compiled binary. Nonetheless, a binary can contain only one or several
94 external objects, as discussed below.</p>
95
96 <H5> <A href="#s4.1.2.1" id="s4.1.2.1"> 4.1.2.1. Compiled objects</A> </H5>
97
98 <p> Compiled objects are binaries compiled from code (like C or C++).
99 They have to be compiled to match your Pd application. Pd is made available for
100 different Operating Systems, namely Linux, macOS and Windows. Moreover, it is
101 available for different CPU architectures and numerical precision (32-bit or 64-bit
102 floats aka "single-precision floating point numbers" or "double-precision floating
103 point numbers" respectively "single" or "double").</p>
104
105 <p>In <A href="3.installing.configuring.htm">Chapter 3: Installing and configuring Pd</A> you can see
106 how to download different Pd applications. Most commonly, you'll have Pd installed
107 as a 64-bit application, which corresponds to most recent systems.</p>
108
109 <p>A Pd application compiled for 32-bit systems is mostly suited to run old externals
110 that were not yet compiled for 64-bit systems. Most relevant and maintained externals
111 are provided for 64-bit systems though; but of course, there can be cases where one is
112 running Pd on an (old) system that only supports 32-bit applications.</p>
113
114 <p>Also, at this point, Pure Data does not officially support double-precision numbers.
115 You can download <b>Pd64</b> beta releases or compile them yourself though (for
116 compilation instructions, see <A href="6.building.from.source.htm">Chapter 6: Building Pd from source</A>).
117 Note that the numerical resolution of Pd and Pd64 here must not be confused with the
118 register size of the system it's running on.</p>
119
120 <p>The Pd64 application requires specially compiled externals. As this is a recent
121 development and not yet fully supported, only a few libraries are currently available.</p>
122
123 <p>You can have externals for different operating systems, architectures, and even
124 for single- and double-precision numbers (i.e., for Pd and Pd64) in the same folder with
125 different file extensions. Refer to the table below for common combinations:</p>
126
127 <figure>
128 <table class="center">
129 <thead>
130 <tr>
131 <th>OS</th>
132 <th>CPU-architecture</th>
133 <th>Pd / Pd64</th>
134 <th class="left">extension</th>
135 </tr>
136 </thead>
137 <tbody>
138 <tr>
139 <td>Linux </td>
140 <td><em>unspecified</em> (any architecture)</td>
141 <td>Pd</td>
142 <td class="left"><code>.pd_linux</code> </td>
143 </tr>
144 <tr>
145 <td>&lsquo;&rsquo;</td>
146 <td>i386 (32-bit)</td>
147 <td>Pd</td>
148 <td class="left"><code>.l_i386</code></td>
149 </tr>
150 <tr>
151 <td>&lsquo;&rsquo;</td>
152 <td>&lsquo;&rsquo;</td>
153 <td>Pd</td>
154 <td class="left"><code>.linux-i386-32.so</code></td>
155 </tr>
156 <tr>
157 <td>&lsquo;&rsquo;</td>
158 <td>&lsquo;&rsquo;</td>
159 <td>Pd64</td>
160 <td class="left"><code>.linux-i386-64.so</code></td>
161 </tr>
162 <tr>
163 <td>&lsquo;&rsquo;</td>
164 <td>amd64/x86_64 (64-bit)</td>
165 <td>Pd</td>
166 <td class="left"><code>.l_amd64</code></td>
167 </tr>
168 <tr>
169 <td>&lsquo;&rsquo;</td>
170 <td>&lsquo;&rsquo;</td>
171 <td>Pd</td>
172 <td class="left"><code>.linux-amd64-32.so</code></td>
173 </tr>
174 <tr>
175 <td>&lsquo;&rsquo;</td>
176 <td>&lsquo;&rsquo;</td>
177 <td>Pd64</td>
178 <td class="left"><code>.linux-amd64-64.so</code></td>
179 </tr>
180 <tr>
181 <td>&lsquo;</td>
182 <td>arm (32-bit)</td>
183 <td>Pd</td>
184 <td class="left"><code>.l_arm</code> </td>
185 </tr>
186 <tr>
187 <td>&lsquo;&rsquo;</td>
188 <td>&lsquo;&rsquo;</td>
189 <td>Pd</td>
190 <td class="left"><code>.linux-arm-32.so</code></td>
191 </tr>
192 <tr>
193 <td>&lsquo;&rsquo;</td>
194 <td>&lsquo;&rsquo;</td>
195 <td>Pd64</td>
196 <td class="left"><code>.linux-arm-64.so</code></td>
197 </tr>
198 <tr>
199 <td>&lsquo;&rsquo;</td>
200 <td>arm64/aarch64 (64-bit)</td>
201 <td>Pd</td>
202 <td class="left"><code>.l_arm64</code></td>
203 </tr>
204 <tr>
205 <td>&lsquo;&rsquo;</td>
206 <td>&lsquo;&rsquo;</td>
207 <td>Pd</td>
208 <td class="left"><code>.linux-arm64-32.so</code></td>
209 </tr>
210 <tr>
211 <td>&lsquo;&rsquo;</td>
212 <td>&lsquo;&rsquo;</td>
213 <td>Pd64</td>
214 <td class="left"><code>.linux-arm64-64.so</code></td>
215 </tr>
216 </tbody>
217 <tbody>
218 <tr>
219 <td>macOS </td>
220 <td><em>unspecified</em> (any architecture)</td>
221 <td>Pd</td>
222 <td class="left"><code>.pd_darwin</code> </td>
223 </tr>
224 <tr>
225 <td>&lsquo;&rsquo;</td>
226 <td>fat (multiple archs)</td>
227 <td>Pd</td>
228 <td class="left"><code>.d_fat</code> </td>
229 </tr>
230 <tr>
231 <td>&lsquo;&rsquo;</td>
232 <td>&lsquo;&rsquo;</td>
233 <td>Pd</td>
234 <td class="left"><code>.darwin-fat-32.so</code></td>
235 </tr>
236 <tr>
237 <td>&lsquo;&rsquo;</td>
238 <td>&lsquo;&rsquo;</td>
239 <td>Pd64</td>
240 <td class="left"><code>.darwin-fat-64.so</code></td>
241 </tr>
242 <tr>
243 <td>&lsquo;&rsquo;</td>
244 <td>i386 (32-bit)</td>
245 <td>Pd</td>
246 <td class="left"><code>.d_i386</code></td>
247 </tr>
248 <tr>
249 <td>&lsquo;&rsquo;</td>
250 <td>&lsquo;&rsquo;</td>
251 <td>Pd</td>
252 <td class="left"><code>.darwin-i386-32.so</code></td>
253 </tr>
254 <tr>
255 <td>&lsquo;&rsquo;</td>
256 <td>&lsquo;&rsquo;</td>
257 <td>Pd64</td>
258 <td class="left"><code>.darwin-i386-64.so</code></td>
259 </tr>
260 <tr>
261 <td>&lsquo;&rsquo;</td>
262 <td>amd64/x86_64 (64-bit)</td>
263 <td>Pd</td>
264 <td class="left"><code>.d_amd64</code></td>
265 </tr>
266 <tr>
267 <td>&lsquo;&rsquo;</td>
268 <td>&lsquo;&rsquo;</td>
269 <td>Pd</td>
270 <td class="left"><code>.darwin-amd64-32.so</code></td>
271 </tr>
272 <tr>
273 <td>&lsquo;&rsquo;</td>
274 <td>&lsquo;&rsquo;</td>
275 <td>Pd64</td>
276 <td class="left"><code>.darwin-amd64-64.so</code></td>
277 </tr>
278 <tr>
279 <td>&lsquo;&rsquo;</td>
280 <td>arm64/aarch64 (<em>Apple Silicon</em>; 64-bit)</td>
281 <td>Pd</td>
282 <td class="left"><code>.d_arm64</code></td>
283 </tr>
284 <tr>
285 <td>&lsquo;&rsquo;</td>
286 <td>&lsquo;&rsquo;</td>
287 <td>Pd</td>
288 <td class="left"><code>.darwin-arm64-32.so</code></td>
289 </tr>
290 <tr>
291 <td>&lsquo;&rsquo;</td>
292 <td>&lsquo;&rsquo;</td>
293 <td>Pd64</td>
294 <td class="left"><code>.darwin-arm64-64.so</code></td>
295 </tr>
296 </tbody>
297 <tbody>
298 <tr>
299 <td>Windows</td>
300 <td><em>unspecified</em> (any architecture)</td>
301 <td>Pd</td>
302 <td class="left"><code>.dll</code></td>
303 </tr>
304 <tr>
305 <td>&lsquo;&rsquo;</td>
306 <td>i386 (32-bit) </td>
307 <td>Pd</td>
308 <td class="left"><code>.m_i386</code></td>
309 </tr>
310 <tr>
311 <td>&lsquo;&rsquo;</td>
312 <td>&lsquo;&rsquo;</td>
313 <td>Pd</td>
314 <td class="left"><code>.windows-i386-32.dll</code></td>
315 </tr>
316 <tr>
317 <td>&lsquo;&rsquo;</td>
318 <td>&lsquo;&rsquo;</td>
319 <td>Pd64</td>
320 <td class="left"><code>.windows-i386-64.dll</code></td>
321 </tr>
322 <tr>
323 <td>&lsquo;&rsquo;</td>
324 <td>amd64/x86_64 (64-bit)</td>
325 <td>Pd</td>
326 <td class="left"><code>.m_amd64</code></td>
327 </tr>
328 <tr>
329 <td>&lsquo;&rsquo;</td>
330 <td>&lsquo;&rsquo;</td>
331 <td>Pd</td>
332 <td class="left"><code>.windows-amd64-32.dll</code></td>
333 </tr>
334 <tr>
335 <td>&lsquo;&rsquo;</td>
336 <td>&lsquo;&rsquo;</td>
337 <td>Pd64</td>
338 <td class="left"><code>.windows-amd64-64.dll</code></td>
339 </tr>
340 </tbody>
341 </table>
342 <figcaption><u>Table 4.1</u>File extensions for different operating systems, architectures and numerical precision</figcaption>
343 </figure>
344
345 <H5> <A href="#s4.1.2.2" id="s4.1.2.2"> 4.1.2.2. Abstractions</A> </H5>
346
347 <p>You can have a Pd patch behave like an object by loading it into other
348 patches - these are usually called “abstractions” (see
349 <A href="2.theory.of.operation.htm#s2.8.1">2.8.1. Abstractions</A>). Note that some of the
350 externals in “extra” are abstractions (for instance, <b>[rev1~]</b> or <b>[hilbert~]</b>).
351 Like any other Pd patch, an abstraction may contain any kind of objects
352 (internals, compiled externals and even other abstractions).</p>
353
354 <H4> <A href="#s4.1.3" id="s4.1.3"> 4.1.3. External libraries </A> </H4>
355
356 <p>In practical terms, an external library is a collection of external objects
357 of any kind (abstractions or compiled objects). But when it comes to compiled
358 objects, a library can provide several objects as a <b>single binary pack</b>
359 or as a <b>set of separate binaries</b> (where each object has its own binary).</p>
360
361 <p>The “classic” library format is a single binary pack (with two or more
362 externals), but splitting into separate binaries became a very common
363 practice. A single external binary (not part of any set of objects) is still,
364 technically, a library with just one object. But again, the prevailing idea is
365 that a library is just a set of objects.</p>
366
367 <p> It’s important to note that there are differences on how externals are
368 loaded depending if they’re a single binary pack or a set of separate binaries
369 (as explained in the next subsections).</p>
370
371 <H4> <A href="#s4.1.4" id="s4.1.4"> 4.1.4. Types of external libraries </A> </H4>
372
373 <p>Libraries can come in all sorts of ways; as only a collection of
374 abstractions (like "list-abs"), only compiled objects, or both. It can even mix
375 compiled externals both as a <b>set of separate binaries</b> and a <b>single binary
376 pack</b>. Basically, any combination is possible for a set of externals.</p>
377
378 <p>One example that combines all external options is <i>Cyclone</i> (since version 0.3),
379 which provides most of its objects as a <b>set of separate binaries</b>, but also includes
380 a small collection of 12 objects as a <b>single binary pack</b> plus a couple of abstractions.</p>
381
382 <H4> <A href="#s4.1.5" id="s4.1.5"> 4.1.5. Wrapping up section 4.1</A> </H4>
383
384 <p>In short, we have:</p>
385
386 <UL>
387 <LI> <b>Internal objects:</b> Objects that are part of Pd Vanilla's binary.</LI>
388 <LI> <b>External objects:</b> Objects that are <u>NOT</u> part of Pd Vanilla's binary.</LI>
389 <LI> <b>Vanilla objects:</b> Built-in objects in the Pd Vanilla distribution
390 (including internals and a small collection of externals - the "extra" objects).</LI>
391 <LI> <b>Types of external objects:</b> Compiled binaries or abstractions.</LI>
392 <LI> <b>External library:</b> Collection of external objects in any form, be it a
393 <u>single binary pack</u> containing several objects, a <u>set of separate binaries</u> /
394 abstractions or any combination of these.</LI>
395 </UL>
396 <br>
397 <br>
398
399 <H3> <A href="#s4.2" id="s4.2">4.2. GUI (.tcl) plugins </A> </H3>
400
401 <p>There's also a catefgory of GUI externals, mostly known as "GUI plugins".
402 These are .tcl file extensions that offer extra GUI features for the Pd
403 application.</p>
404
405 <p>These plugins are normally offered with the plugin name appended by
406 "-plugin". For example: "completion-plugin", a plugin for autocompleting
407 objcet names. Another interesting plugin is the "patcherize-plugin",
408 which turns bits of patches into subpatches or abstractions. These need
409 to be placed in a search path that Pd knows about (see details in next
410 section). These plugins are then automatically loaded when Pd starts up.</p>
411
412 <p>The actual filename is then something like "completion-plugin.tcl" and
413 it comes inside a folder with the same name (completion-plugin). In this
414 situation, Pd knows to search inside that folder for the plugin!</p>
415
416 <H3> <A href="#s4.3" id="s4.3">4.3. Installing externals and GUI plugins </A> </H3>
417
418 <p>Installing externals and GUI plugins in Pd is quite simple, all you need
419 to do is download them from somewhere (such as from Pd directly as explained
420 later) and include them in a proper folder.</p>
421
422 <H4> <A href="#s4.3.1" id="s4.3.1"> 4.3.1. Where to include externals and GUI plugins</A> </H4>
423
424 <p>Currently, when launching for the first time with a fresh install, Pd asks if
425 you want to create a documents directory for patches that includes an “externals”
426 subdirectory. This externals folder is where it’s advised to include externals
427 and GUI plugins. This path is automatically included in the user added
428 search paths (under the 'Path' tab in Preferences), see figure below.</p>
429
430 <figure>
431 <IMG src="resources/4.3.1.png" ALT="Preferences">
432 <figcaption><u>Fig. 4.3.1</u> The Path preferences with a few user added paths</figcaption>
433 </figure>
434
435 <p>We see in the screenshot above that the “Pd” folder is created
436 under ~/Documents, and inside it we have the "externals" subfolder.
437 Even if you did not create this folder, here is where you can create it
438 by clicking the “Reset” button under “Pd Documents Directory”. The picture
439 also shows other paths for external libraries, all inside the
440 ~/Documents/Pd/externals.</p>
441
442 <p>Externals can actually be anywhere in your computer, but Pd must
443 know where to look for them. Pd looks for files (including externals) in the
444 user added search paths, but it also searches in other folders not listed there
445 such as: the same folder that your patch is saved on (the <u>Relative Path</u>)
446 and the <u>Standard Paths</u>. Note the "Use standard paths" toggle in the picture
447 above, which is on by default. This tells Pd to use these paths, which are:</p>
448
449 <UL>
450 <LI>A) <u>Application-specific</u>: The "extra" folder inside a particular Pure Data
451 application.</LI>
452 <LI>B) <u>User-specific</u>: A system folder for a specific user in the machine.</LI>
453 <LI>C) <u>Global</u>: A system folder for all users on the machine.</LI>
454 </UL>
455
456 <p>Officially, there’s only one ‘Standard Path’ which is the ‘extra’ folder.
457 The others are not automatically created by Pd and are part of an old
458 structure. Currently, the best practice is to use the default external folders or
459 user added paths, but these other options are documented here anyway and
460 may be useful in some edge cases.</p>
461
462
463 <p>The <u>Global</u> folder affects all Pure Data Applications for all users.
464 The <u>User-specific</u> folder affects all Pure Data Applications for that user.
465 And since you can have different versions of Pd installed in your system, the
466 <u>Application-specific</u> folder affects only that particular Pd Application
467 - multiple Pd applications can be of different versions (an older and a newer
468 one or both single and double precision variants). For reference, here’s the
469 list of the Standard Paths for all operating systems:</p>
470
471 <p>A) macOS:</p>
472 <UL>
473 <LI><u>Application-specific</u>: <mark><b>/$PdPath/Contents/Resources/extra</b></mark> - this is
474 inside the Pd Application (like Pd-0.49-1 in ~/Applications); right click it and
475 choose "Show Package Contents", then navigate to "extra".</LI>
476 <LI><u>User-specific</u>: <mark><b>~/Library/Pd</b></mark> (/Users/user_name/Library/Pd)</LI>
477 <LI><u>Global</u>: <mark><b>/Library/Pd</b></mark></LI>
478 </UL>
479
480 <p>B) Windows:</p>
481 <UL>
482 <LI><u>Application-specific</u>: <mark><b> %ProgramFiles(x86)%\Pd\extra</b></mark> (for 64-bit
483 OS and 32-bit Pd) or %ProgramFiles%\Pd\extra; this is
484 inside the Pd Application (usually in C:\Program Files).
485 This folder needs to be set to writeable.</LI>
486 <LI><u>User-specific</u>: <mark><b> %AppData%\Pd</b></mark>
487 (usually in C:\Users\user_name\AppData\Roaming\Pd).</LI>
488 <LI><u>Global</u>: <mark><b> %CommonProgramFiles%\Pd</b></mark>
489 (usually in C:\Program Files\Common Files\Pd).</LI>
490 </UL>
491
492 <p>C) GNU/Linux:</p>
493
494 <UL>
495 <LI><u>Application-specific</u>: <mark><b> /usr/lib/pd/extra</b></mark> if installed via a package
496 manager (apt-get) or /usr/local/lib/pd/extra if compiled by yourself.</LI>
497 <LI><u>User-specific</u>: <mark><b> ~/.local/lib/pd/extra</b></mark> (preferred since version Pd-0.47-1)
498 or ~/pd-externals (deprecated but still usable).</LI>
499 <LI><u>Global</u>: <mark><b> /usr/local/lib/pd-externals</b></mark>.</LI>
500 </UL>
501
502 <H4> <A href="#s4.3.2" id="s4.3.2"> 4.3.2. How to download externals and GUI plugins from Pd</A> </H4>
503
504 <p>Since version 0.47-0, Pd Vanilla has its own external manager! This is a built in
505 .tcl plug-in named "deken" (check <a href="https://github.com/pure-data/deken">
506 https://github.com/pure-data/deken</a> for reference). Open it by selecting the
507 "Find externals" entry from the <b>Tools menu</b>. Then you can type and search for an
508 object name, a library name or both. The wildcard '*' can be used to broaden the search,
509 or an exact name can be used instead. All available versions of the library/external
510 specific for your operating system will be shown to you. See figure below. Note that
511 you can also download GUI plugins from deken. Search for '*-plugin' to get a list of
512 all options.</p>
513
514 <figure>
515 <IMG src="resources/4.3.2.png" ALT="deken install">
516 <figcaption><u>Fig. 4.3.2</u> Installing external libraries from 'deken'</figcaption>
517 </figure>
518
519 <p>When you double-click on library and version you want, by default Pd downloads it to
520 "~/Documents/Pd/externals". Note you can click on multiple libraries and download
521 them at the same time. Note also you can search for multiple objects and libraries by
522 separating the search entries with commas.</p>
523
524 <figure>
525 <IMG src="resources/4.3.3.png" ALT="installing multiple libraries">
526 <figcaption><u>Fig. 4.3.3</u> Installing multiple libraries at once</figcaption>
527 </figure>
528
529 <p>Moreover, if you have a an object creation error in the console, you can
530 right click on the error to open a context menu with a "Find externals" entry.
531 This will open the plugin manager with a prompt search for the missing object ready to go.</p>
532
533 <figure>
534 <IMG src="resources/4.3.4.png" ALT="searching object for creation error">
535 <figcaption><u>Fig. 4.3.4</u> Searching object in the plugin manager via the console window error</figcaption>
536 </figure>
537
538 <p>Note that when the external manager window is focused, there are
539 dedicated menus: <b>File</b> and <b>Edit</b>. You can use <b>File</b>
540 to open and install a ".dek" file, and <b>Edit</b> to open "Preferences"
541 for the plugin manager. For macOS these menus are on the top bar.</p>
542
543 <figure>
544 <IMG src="resources/4.3.5.png" ALT="plugin manager menus">
545 <figcaption><u>Fig. 4.3.5</u> The plugin manager's menus</figcaption>
546 </figure>
547
548 <p>And the plugin manager's preferences are as follows:</p>
549
550 <figure>
551 <IMG src="resources/4.3.6.png" ALT="deken preferences">
552 <figcaption><u>Fig. 4.3.6</u> The plugin manager's preferences</figcaption>
553 </figure>
554
555 <p>The above are the default settings. If you want to see results that are not
556 suited for your system, uncheck "Hide foreign architectures". If you want to
557 find older versions of the library, uncheck "Only show the newest version of
558 a library".</p>
559
560 <H3> <A href="#s4.4" id="s4.4">4.4. Loading externals </A> </H3>
561
562 <p>The current best practice is to use the <b>[declare]</b> object to search for,
563 load and manage externals, but there are alternatives.</p>
564
565 <p>If the object is from a library that is distributed as a single binary pack,
566 this binary needs to be pre loaded at start time by Pd, so it can create its
567 externals. This is done either with <b>[declare]</b> or manually via the 'Startup' tab
568 in Preferences.</p>
569
570 <p>If the external library only contains abstractions or objects compiled as
571 a set of separate binaries, Pd just needs to know its path. Again, this can be
572 done via <b>[declare]</b> or manually via the 'Path' tab in Preferences, but yet
573 another option here is to use slash declarations as we'll see later.</p>
574
575 <H4> <A href="#s4.4.1" id="s4.4.1">4.4.1. Using the <b>[declare]</b> object</A> </H4>
576
577 <p>The <b>[declare]</b> object can be used to add search paths or load libraries. When
578 adding a path, it behaves quite similarly to adding search paths to the
579 user added paths via the 'Path' tab in Preferences. The difference is that this
580 will only work for the patch that contains this <b>[declare]</b> object - unlike using
581 Path preferences, which loads the path(s) permanently for any patch.</p>
582
583 <p>As for loading a library, once Pd loads it (via <b>[declare]</b> or startup) it
584 sticks with it. This means that if you use <b>[declare]</b> to load a library, it will
585 also be loaded if you create a new patch without any <b>[declare]</b> object.</p>
586
587 <H5> <A href="#s4.4.1.1" id="s4.4.1.1">4.4.1.1. [declare -path]</A> </H5>
588
589 <p>Let's take for an example the <a href="http://github.com/porres/pd-else"> ELSE</a>
590 library. This library mostly contains separate binaries and abstractions, so Pd only
591 needs to know its location path to load them. We then use the '-path' flag as in
592 [declare -path else]. This makes Pd look for a folder named 'else' to add it to the
593 search path for that patch only.If it succeeds, this is where Pd will prioritize the
594 search of objects and other files, moving on to other possible search places if
595 nothing is found.</p>
596
597 <p>But where does Pd look for the 'else' folder? Well, the -path flag is first meant
598 to search in the Relative Path, but if it doesn't find it, it falls back to the
599 User Added Paths and Standard Paths. So let’s say you put the ELSE library folder in
600 “~/Documents/Pd/externals”, which is the current best practice, Pd will know to look
601 for it there and will find it!</p>
602
603 <p> Now, in the case of a single external, the best practice is to include it in
604 a folder with the same name in “~/Documents/Pd/externals”. An example, the <b>[freeverb~]</b>
605 external should be in “~/Documents/Pd/externals/freeverb~”. In this situation, you don’t
606 need to add the external folder to the path, manually or use <b>[declare]</b>. This is because
607 when you tell Pd to look for an external, if it finds a folder with the same name as the
608 external, it'll know to search inside that folder for the external!</p>
609
610 <H5> <A href="#s4.4.1.2" id="s4.4.1.2"> 4.4.1.2. [declare -lib]</A> </H5>
611
612 <p>The '-lib' flag is needed for the classic Pd library format, which
613 is a single binary pack with many externals. One such example is the
614 <a href="https://git.iem.at/pd/zexy/"> Zexy </a> library. So you should
615 download and have the 'zexy' folder in “~/Documents/Pd/externals/zexy”.
616 Now you can use <b>[declare -lib zexy]</b> to load the external binary. In the
617 same way as explained with the <b>[freeverb~]</b> example, the binary is inside
618 a folder with the same name. So Pd will search for the external in
619 “~/Documents/Pd/externals", will find the 'zexy' folder and know to
620 search for the zexy binary in it. This means you don't need to bother in
621 using <b>[declare]</b> to define the search path.</p>
622
623 <p>Note that it may be possible for you to load a library binary as an object
624 if the developer wished to. But it's still advisable to use either "Startup"
625 or <b>[declare -lib]</b>, because this way you are sure the library is preloaded
626 before Pd tries to create other objects in your patch.</p>
627
628 <p>The ELSE library also offers a binary for you to load as a library. This is
629 a very special case as this binary does not actually load any external. What
630 it actually loads are some .tcl plugins that add an object browser at right
631 clicking on a patch canvas. It also prints information about the release on
632 the Console window. Moreover, you can also load <b>[else]</b> as an object in a patch
633 and it offers the functionality of outputting its version for you to check in
634 the patch if it is the correct one.</p>
635
636 <p>The Cyclone library also allows you to load <b>[cyclone]</b> as an object and
637 offers the same version output functionality as in ELSE.</p>
638
639 <p>For more details on how <b>[declare]</b> works, please check its help file!</p>
640
641 <H4> <A href="#s4.4.2" id="s4.4.2"> 4.4.2. Load via path and startup</A> </H4>
642
643 <p>We'll now see the differences between using <b>[declare]</b> or using "Path" and
644 "Startup" tabs in Preferences.</p>
645
646 <H5> <A href="#s4.4.2.1" id="s4.4.2.1"> 4.4.2.1. User added path</A> </H5>
647
648 <p>One big difference in adding a search path in 'Preferences' is that this
649 permanently adds the path and works every time Pd starts and for any patch
650 you open. When you use <b>[declare]</b>, the path is loaded only for its owning
651 patch and loaded abstractions. Moreover, if you have an abstraction with
652 [declare -path], it'll only work for that abstraction and not the parent
653 patch! Hence, <b>[declare]</b> allows a much better control and management of
654 paths. But you may want to permanently add a path in your own system if
655 you know exactly what you have and what you need.</p>
656
657 <p>We’ve seen that even if you have a folder in “~/Documents/Pd/externals”
658 you still need to tell Pd to look for it. You can manually add a User Added
659 Paths in Preferences => Path by clicking “New”.</p>
660
661 <p>Another possibility is that under deken’s preferences tabs you can click
662 on “Add newly installed libraries to Pd’s search Path”, which adds downloaded
663 libraries to the user added search paths (see picture above).</p>
664
665 <p>Note also that having a user added search path will not make it have search
666 priority like it happens when you use <b>[declare]</b>. In this case, the path relative
667 to the patch will have top priority!</p>
668
669 <H5> <A href="#s4.4.2.2" id="s4.4.2.2"> 4.4.2.2. Startup</A> </H5>
670
671 <p>"Preferences => Startup" loads a window that says <i>"Pd libraries to load
672 on startup"</i>. This is where you can manually and permanently load single
673 binary pack libraries. But since they're only needed during startup, you need
674 to restart Pd so this takes effect. The startup is also used for configuring
675 Pd in many ways, see <a href="3.installing.configuring.htm#s3.4.1">3.4.1 Startup flags</a> for
676 details.</p>
677
678 <figure>
679 <IMG src="resources/4.4.1.png" ALT="startup preferences">
680 <figcaption><u>Fig. 4.4.1</u> The Startup preferences with library binaries to load</figcaption>
681 </figure>
682
683 <p> As we’ve seen with ‘zexy’, it’s common that the name of the binary is
684 the same as the library’s, so you don’t need to worry about adding it to the
685 path. There are many other examples in the picture above. One particularity
686 <a href="https://github.com/umlaeute/Gem"> Gem </a> is that it also forces
687 Pd to add its path to the search paths, which is needed for some abstractions
688 and then you don’t need to bother adding it to the path. Note, however, that
689 unlike using <b>[declare]</b>, this does not enforce a top search priority! Hence,
690 for example, you may prefer to use <b>[declare -path Gem -lib Gem]</b> instead.</p>
691
692 <p>It all depends on the developer, but it is a common and good practice that
693 when you load a library, Pd’s terminal window will print something to tell us
694 that the libraries were loaded successfully. Here’s a screenshot of the result
695 of loading cyclone.</p>
696
697 <figure>
698 <IMG src="resources/4.4.2.png" ALT="lib print">
699 <figcaption><u>Fig. 4.4.2</u> Library loading printout</figcaption>
700 </figure>
701
702 <p>Note that when you load a library via Startup or <b>[declare -lib]</b>, all of its
703 external objects are loaded in Pd and they have search priority over other
704 externals that are loaded via paths. This may cause issues discussed on the
705 next section.</p>
706
707 <H4> <A href="#s4.4.3" id="s4.4.3"> 4.4.3. Load using slash declarations</A> </H4>
708
709 <p>Let’s say you’ve downloaded the ELSE library into ~/Documents/Pd/externals.
710 Instead of using <b>[declare -path else]</b> or adding the ELSE folder to the user
711 added paths manually, you can just prepend “else/“ before an object name. This
712 will make Pd look for this object in a folder called ‘else’ in one of its search
713 paths (which includes ~/Documents/Pd/externals) and find it! Here’s an example:</p>
714
715 <figure>
716 <IMG src="resources/4.4.3.png" ALT="slash declaration">
717 <figcaption><u>Fig. 4.4.3</u> An external object with a slash declaration</figcaption>
718 </figure>
719
720 <p>This can be an option that some people may prefer for the simple fact that
721 it's just clearer from which library folder we're loading the external. But
722 there are some rare cases where this is the only way to guarantee you have
723 loaded the correct external, which is a problem when you have too many
724 libraries in your system and are using more than one that has an external
725 with the same name. Hence, some external libraries like 'Cyclone' and 'ELSE'
726 use this in the documentation of the help files to make sure you load the
727 correct external.</p>
728
729 <p>Note, however, that this is not possible for an external that is loaded as
730 part of a single binary pack, unless the developer uses a workaround to add
731 this possibility as alternative.</p>
732
733 <p>The issue with <b>[declare]</b> or adding a path to the user added paths is that
734 it'll respect a search order. Whatever path is added first in the search list
735 order has a priority, and where ever Pd finds an external first, it'll load
736 it and stop searching elsewhere. Again, this kind of problem is not that
737 common, but you can solve this with slash declarations. You may also be able
738 to sort this issue by setting the desired order. This is quite easy in
739 <b>[declare]</b> as which ever -path comes first in the list has a priority, so you
740 can try that if you want to avoid slash declarations when you run into this
741 rare issue.</p>
742
743 <p>Name clash conflicts can also happen when you're loading single binary
744 pack libraries. The problem is that once they get loaded, all of its external
745 objects are now part of Pd and have a priority in the search. Here's an
746 example, the 'ceammc' library is a single binary pack and it included an
747 object called <b>[xfade~]</b>. The ELSE library has separate binaries for each
748 object and also has one called <b>[xfade~]</b>. If you're using both libraries,
749 ceammc's <b>[xfade~]</b> object will have priority and it doesn't help you to have
750 [declare -path else].</p>
751
752
753 <p>It was mentioned how a library name prefix may also be possible in the
754 context of single binary packs. The ceammc library offers this, so you can
755 also load its <b>[xfade~]</b> object as <b>[ceammc/xfade~]</b>. But note that this still
756 requires you to preload the binary (via startup or <b>[declare]</b>). The slash
757 declaration here was only possible because the developer added the
758 'ceammc/xfade~' name as an alternative option in the code. So it is just a
759 hack to improve the limitation of Pd in handling namespaces. Another library
760 that does this is Cyclone, which carries a sublibrary with 12 objects with
761 non alphanumeric names, such as <b>[>~]</b>. By using the same trick, you can create
762 the <b>[>~]</b> object as <b>[cyclone/>~]</b>. Another single binary pack library that has
763 <b>[>~]</b> is zexy, so this way you can make sure you're getting cyclone's instead.</p>
764
765 <p>These issues might be clear if you better understand how Pd works when
766 loading externals. See next subsection.</p>
767
768 <H3> <A href="#s4.5" id="s4.5">4.5. How external binaries are loaded</A> </H3>
769
770 <p>Once you make sure Pd can load an external binary via a path, this is what
771 happens when you create it. Whenever you create an object that Pd
772 doesn't yet know about, Pd looks for the object file named as, for
773 instance, "profile.pd_linux". Pd looks first in a path defined by
774 <b>[declare]</b> (if any, of course), then in the directory containing
775 the patch, then in directories listed as user added paths in the
776 order they are listed, then in the standard paths. As soon as Pd
777 finds the object in this search order, it'll stop searching further
778 more and will add the found object to its "class list", which is
779 the set of all Pd classes you can use. Pd then tries to create the
780 object you asked for, and if everything is fine with it, this
781 happens successfully (creation errors are given otherwise).</p>
782
783 <p>In the case of a single binary pack loaded at Startup or with
784 <b>[declare]</b>, all the externals it contains get preloaded in Pd's class
785 list, even though they're only created in object boxes when you
786 require them.</p>
787
788 <p>In both cases, once an external object's binary is in Pd's memory,
789 there is no real difference between it and a native object. They're
790 all seen equally now in Pd. Once a new separate binary or single binary
791 pack is loaded, it's there for the duration of your Pd session. This
792 means that if you replace the binaries, the objects won't be updated
793 even if you recreate them. You can also even delete the binary as Pd
794 now carries it for good in its memory. Hence, if you're working on the
795 development of an object's binary and decide to change it, you have to
796 exit and re-enter Pd to get the change to take effect.</p>
797
798 <p>Let us just make the distinction that external abstractions work
799 quite differently! As they get updated any time they’re updated and
800 reloaded!</p>
801
802
803 <H4> <A href="#s4.5.1" id="s4.5.1"> 4.5.1. Overriding objects (externals and native)</A> </H4>
804
805 <p>We've seen that Pd loads and sticks to an external binary,
806 but they can get overridden. For instance, if you create <b>[xfade~]</b>
807 from ELSE and then load ceammc's binary later (that also has an
808 <b>[xfade~]</b> object), Pd only knows about <b>[xfade~]</b> from ceammc! It's
809 been also noted how cyclone and zexy have objects with the same
810 name. If you first load cyclone's binary and zexy's later, zexy's
811 objects with the same name (such as <b>[>~]</b>) will override and prevail.</p>
812
813 <p>And here's an interesting feature, you can also override internal
814 objects with externals! Say you have an external called <b>[phasor~]</b>.
815 If it's a single binary, you can force Pd to find it with slash
816 declarations. Otherwise, if it's a binary pack, you can load as any
817 other library and if it has objects with the same name as vanilla's
818 internals, they get overridden! But Pd still keeps a copy of the old
819 one and renames it by appending "_aliased", so you can still load the
820 old "phasor~", for instance, as <b>[phasor~_aliased]</b>. You probably
821 don't want to mess with overriding internals, but it makes sense if you
822 provide new versions with more features that are fully backwards compatible.</p>
823
824 <H3> <A href="#s4.6" id="s4.6"> 4.6. Search order in Pd for objects and files</A> </H3>
825
826 <p>This information has been provided in pieces throughout this section of the Manual. But
827 now well wrap it up after all the information has been presented.</p>
828
829 <p>So, whenever you tell Pd to create an object in its box, this is what happens.</p>
830
831 <p><b>First</b> it searches in its object list. This includes all of Pd's internals and
832 other externals that may have been previously loaded.</p>
833
834 <p><b>Second</b> it moves on to unknown objects in possible paths. And if you have
835 [declare -path] in your patch, the defined path(s) has/have priority respecting
836 the order they are listed from left to right.</p>
837
838 <p><b>Third</b> is time to search the path relative to the patch.</p>
839
840 <p><b>Fourth</b> it goes to the user added paths, defined at "Path"
841 in "Preferences". An order is also respected, from top to bottom.</p>
842
843 <p><b>Fifth</b> and last, it searches the "standard paths", which
844 includes the 'extra' library provided by the Pd Vanilla distribution.
845 Note you can use <b>[declare -stdpath ./]</b> to force priority to search
846 this folder!</p>
847
848 <p>Regarding files, the search order is the same, only the
849 first step is ignored.</p>
850
851 </div>
852 <div class="nav nav-bottom">
853 <div class="nav-back"><A href="3.installing.configuring.htm">&lt; Chapter 3: Installing and configuring Pd</A></div>
854 <div class="nav-home"><A href="index.htm#s4">Table of contents</A></div>
855 <div class="nav-forward"><A href="5.current.status.htm">Chapter 5: Current status &gt;</A></div>
856 </div>
857
858 </BODY>
859 </HTML>