From a6c602f1ef5ba80e443a342c1c7ee2d0a4c775f7 Mon Sep 17 00:00:00 2001 From: Albert Graef Date: Wed, 2 Oct 2024 00:24:19 +0200 Subject: [PATCH] Update the Pd html manual to 0.54. --- pd/doc/1.manual/index.htm | 4 + pd/doc/1.manual/pdmanual.css | 2 +- pd/doc/1.manual/x2.htm | 99 ++++++++---- pd/doc/1.manual/x4.htm | 298 +++++++++++++++++++++++++++-------- pd/doc/1.manual/x5.htm | 60 ++++++- pd/doc/1.manual/x6-a.htm | 158 +++++++++++++++---- pd/doc/1.manual/x6-c.htm | 150 ++++++++++++++++++ pd/doc/1.manual/x6.htm | 22 ++- 8 files changed, 653 insertions(+), 140 deletions(-) create mode 100644 pd/doc/1.manual/x6-c.htm diff --git a/pd/doc/1.manual/index.htm b/pd/doc/1.manual/index.htm index 0f1c7daa6..d606c6a89 100644 --- a/pd/doc/1.manual/index.htm +++ b/pd/doc/1.manual/index.htm @@ -69,6 +69,7 @@

Pd Manual

  • converting to and from messages
  • switching and blocking
  • nonlocal signal connections +
  • multichannel signals
  • scheduling
      @@ -163,6 +164,9 @@

      Pd Manual

    1. requirements
    2. autotools build (recommended)
    3. Linux & BSD +
        +
      1. BSD
        2. +
    4. macOS
      1. macOS resources
        2. diff --git a/pd/doc/1.manual/pdmanual.css b/pd/doc/1.manual/pdmanual.css index b49acfa6c..fd59bfe1a 100644 --- a/pd/doc/1.manual/pdmanual.css +++ b/pd/doc/1.manual/pdmanual.css @@ -18,7 +18,7 @@ BODY { #corpus { - width: 6.5in; + width: 8.5in; margin-left: 0.8in; } diff --git a/pd/doc/1.manual/x2.htm b/pd/doc/1.manual/x2.htm index 8bfcef74d..226bc8ec0 100644 --- a/pd/doc/1.manual/x2.htm +++ b/pd/doc/1.manual/x2.htm @@ -9,7 +9,7 @@ - + @@ -30,7 +30,7 @@

        Pd Manual chapter 2: theory of operation

        The purpose of this chapter is to describe Pd's design and how it is -supposed to work. Practical details about how to obtain, install, and run Pd +supposed to work. Practical details about how to obtain, install, and run Pd are described in the next chapter. Links to more extensive guides (and to more theoretical information about computer music) can be found in the previous chapter. @@ -38,11 +38,16 @@

        Pd Manual chapter 2: theory of operation

        2.1 overview

        Pd is a real-time graphical programming environment for audio and graphical -processing. It resembles the Max/MSP system but is much simpler and more -portable; also Pd has two features not (yet) showing up in Max/MSP: first, -via Mark Dank's GEM package, Pd can be used for simultaneous computer -animation and computer audio. Second, an experimental facility is provided -for defining and accessing data structures. +processing. It resembles the MAX system but is much simpler and more portable. +For example, with Peter Brinkmann's libpd you can have Pure Data as an embeddable +audio synthesis library. Also Pd has an experimental facility not present in MAX +that is provided for defining and accessing data structures. + +

        Even though it is light and portable, Pd has many external packages that +expand its features, like Mark Dank's GEM package which expands Pd to be used +for simultaneous computer animation and computer audio. Similarly, Zack Lee's Ofelia +package allows you to use openFrameworks and Lua within Pd for creating audiovisual +artwork or multimedia applications such as games.

        2.1.1. the main window, canvases, and printout

        @@ -68,7 +73,7 @@

        2.1.1. the main window, canvases, and printout

        devices Pd is using. The "Media" menu is also provided, with accelerators "Control-." to turn audio computation off and "Control-/" to turn it on. When audio is on, Pd is computing audio samples in real time according to whatever -patches you have open (whether they are visible or not). +patches you have open (whether they are visible or not).

        The DIO (Digital I/O) error indicator flashes if there is a synchronization error for audio input or output. (But note that on some platforms Pd doesn't @@ -135,7 +140,7 @@

        2.1.2. object boxes

        The text you type into an object box determines how many and what kinds of inlets and outlets the object will have. Some -classes (like "+" always have a fixed arrangement of inlets and outlets, +classes (like "+" always have a fixed arrangement of inlets and outlets, and in the case of other classes, the inlets and outlets will depend on the creation arguments. @@ -200,7 +205,7 @@

        2.1.3. message and GUI boxes

        sliders, and so on. Whereas the appearance of an object or message box is static when a patch is running, a number box's contents (the text) changes to reflect the current value held by the box. You can also use a number box as a -control by clicking and dragging up and down, or by typing values in it. +control by clicking and dragging up and down, or by typing values in it. (There are also shift- and alt-click actions; see getting help to find out how to look this up). @@ -282,7 +287,7 @@

        2.2.5. changing the text

        If you click a box and move the mouse without releasing the button this displaces the entire box. If you wish to displace a box which is already selected, first de-select the box by clicking outside it; otherwise you will be -selecting text instead of moving the box. +selecting text instead of moving the box.

        The updated text only becomes part of the patch when you de-select the object. Changing the text in an "object" box deletes the old @@ -291,7 +296,7 @@

        2.2.5. changing the text

        2.2.6. connecting and disconnecting boxes

        To make a connection between two boxes, click on any outlet of the first -one, drag toward an inlet of the second one, and release. You can +one, drag toward an inlet of the second one, and release. You can release the mouse button anywhere within the target object and the connection will be made to the nearest inlet. @@ -338,7 +343,7 @@

        2.3.1. anatomy of a message

        16777216. (In Max, there are separate data types for integers and floating point numbers; Pd uses only float.) -

        When a message is passed to something (which is often an inlet of a box +

        When a message is passed to something (which is often an inlet of a box but could be anything that can receive a message), the selector of the message is checked against the receiver. If the receiver recognizes messages of that selector, it carries out some corresponding action. For instance, here is a @@ -434,7 +439,7 @@

        The "trigger" object, abbreviated "t", can be used to split out connections from a single outlet in a determinate order. By convention, all objects in Pd, when sending messages out more than one outlet, do so from right to left. If -you connect these to inlets of a second object without crossing wires, the +you connect these to inlets of a second object without crossing wires, the second object will get its leftmost inlet last, which is usually what you want. Here is how to use "trigger" to disambiguate the previous example: @@ -546,7 +551,7 @@

        2.4.2. tilde objects and audio connections

        an error to connect an audio outlet to a non-audio inlet or vice versa; usually these errors are detected at "sort time" when audio is started or the network changed with audio running. An object's leftmost inlet may accept both audio -and messages; any other inlet is either one or the other. +and messages; any other inlet is either one or the other.

        The audio network, that is, the tilde objects and their interconnections, @@ -588,7 +593,7 @@

        2.4.4. switching and blocking

        setting the block size also sets the number of FFT channels. You may wish to use block sizes smaller than 64 to gain finer resolutions of message/audio interaction, or to reduce "block delay" in feedback algorithms. At the -(untested) extreme, setting the block size to one allows you to write your +extreme, setting the block size to one allows you to write your own recursive filters.

        You can use switch~ to budget your DSP computations; for instance you might @@ -614,7 +619,7 @@

        2.4.5. nonlocal signal connections

        more than one catch~. You can reset the destination of a throw~ if you want to.

        Send~ just saves a signal which may then be receive~d any number of times; but -a receive~ can only pick up one send~ at a time (but you can switch between +a receive~ can only pick up one send~ at a time (but you can switch between send~s if you want.)

        Don't try to throw~ and catch~ or send~ and receive~ between windows with @@ -631,6 +636,33 @@

        2.4.5. nonlocal signal connections

        delread~ after you created the delwrite~; if things get out of whack, just delete and re-create the delread~. +

        2.4.6. multichannel signals

        + +

        As of Pd version 0.54, signals may be multichannel. Every signal has a +length equal to the window's block size (64 by default), and also has a +channel count which is 1 by default. The snake~ object can combine any +number of single-channel signals into a multichannel one, or alternatively can +split a multichannel signal into its component single-channel ones. Non-local +connections (send~, receive~, throw~, catch~, inlet~, outlet~) can be used to +pass multichannel signals from window to window, and dac~ and adc~ can input and +output several inputs or outputs into, or out of, one multichannel signal. + +

        The receive~, catch~, and adc~ objects take arguments to specify the desired +number of channels. + +

        Stateless objects, which have no memory from one DSP tick to the next, have +all been adapted to handle multichannel inputs and outputs. The arithmetic and +math objects (+~, -~, *~ ,/~, wrap~, sqrt~, and so on) use their inputs to determine +their channel counts. Binary operations like "+" can combine single- and +multiple-channel inputs. + +

        Other objects such as filters or oscillators have not been adapted for +multichannel signals because there might be many ways to design multichannel +versions of them. Instead, you can use the clone object to perform general +operations on multichannel signals. Signal inputs and outputs of cloned patches +can be used to distribute multichannel signals among the individual cloned +patches. +

        2.5. scheduling

        Pd uses 64-bit floating point numbers to represent time, providing sample @@ -728,7 +760,7 @@

        2.6.1. creation of objects

        2.6.2. persistence of data

        Among the design principles of Pd is that patches should be printable, in the -sense that the appearance of a patch should fully determine its functionality. +sense that the appearance of a patch should fully determine its functionality. For this reason, if messages received by an object change its action, since the changes aren't reflected in the object's appearance, they are not saved as part of the file which specifies the patch and will be forgotten when the patch is @@ -737,7 +769,7 @@

        2.6.2. persistence of data

        as specified by creation arguments.)

        An exception is made for subpatches whose "state" is the configuration of -the subpatch; as a special case, this configuration is restored when the +the subpatch; as a special case, this configuration is restored when the patch is read from a file. Also, if you rename the subpatch, for instance typing "pd jane" instead of "pd spot," the contents of the patch are preserved and only the text in the object box and the window title of the subpatch are @@ -785,7 +817,7 @@

        2.6.4. inlets and lists

        Unless they arrange otherwise by defining a "list" method, objects respond to the "list" message by distributing the arguments of the message to their inlets, except for the first argument which is passed as a "float" or -"symbol" message to the object proper. +"symbol" message to the object proper.

        2.6.5. dollar signs

        @@ -842,10 +874,10 @@

        2.7. subpatches

        The objects, "inlet,", "inlet~," "outlet," and "outlet~,", when put in a subpatch, create inlets and outlets for the object box containing the subpatch. -This works equally for one-off subpatches and abstractions and only accept control -data messages. The inlet~ and outlet~ versions create inlets and outlets for audio +This works equally for one-off subpatches and abstractions and only accept control +data messages. The inlet~ and outlet~ versions create inlets and outlets for audio signals. Note you can also mix control messages in an inlet~ with the 'fwd' argument -but a signal outlet only takes signals. Inlets and outlets appear on the invoking box +but a signal outlet only takes signals. Inlets and outlets appear on the invoking box in the same left-to-right order as they appear in the subpatch.

        2.7.1. abstractions

        @@ -887,6 +919,10 @@

        2.7.1. abstractions

        "$" argument is expanded at creation time, and in a message box, at message time. +

        A "clone" object is provided to automatically create and manage multiple copies +of an abstraction. You can use it to make voice banks for polyphonic synthesis, +for example. +

        2.7.2. Graph-on-parent subpatches

        If you open the "properties" dialog for a subpatch or an abstraction, you can @@ -1015,7 +1051,7 @@

        2.9. Data structures

        The original idea in developing Pd was to make a real-time computer music performance environment like Max, but somehow to include also a facility for -making computer music scores with user-specifiable graphical representations. +making computer music scores with user-specifiable graphical representations. This idea has important precedents in Eric Lindemann's Animal and Bill Buxton's SSSP. An even earlier class of precedents lies in the rich variety of paper scores for electronic music before it became practical to offer a @@ -1060,7 +1096,7 @@

        2.9. Data structures

        colored ones.) This is all specified by the user using Pd's "template" mechanism. -

        Here is the template associated with the graphical objects +

        Here is the template associated with the graphical objects shown above:

        template for graphical score

        @@ -1068,7 +1104,7 @@

        2.9. Data structures

        Templates consist of a data structure definition (the "struct" object) and zero or more drawing instructions ("filledpolygon" and "plot"). The "struct" object gives the template the name, "template-toplevel." The data structure -is defined to contain three floating point numbers named "x", "y", and +is defined to contain three floating point numbers named "x", "y", and "voiceno," and two arrays, one named "pitch" whose elements belong to another template named "template-pitch," and similarly for the array "amp." @@ -1160,7 +1196,7 @@

        2.9.1. Traversal

        black.

        The details of extracting the pitch and dynamic breakpoints from the arrays -defined in the template are managed in the "voice" abstraction. +defined in the template are managed in the "voice" abstraction. The "voice" abstraction receives a pointer to a given object and manages the sequencing of the arrays; so it @@ -1204,8 +1240,8 @@

        2.9.2. Accessing and changing data

        the number of elements in the array. For lists, an "append" object appends a new scalar for a given template to a list, after the element pointed to. (To insert a scalar at the beginning of a list, the pointer can be set to -the "head" of the list, a formal location before the first list item.) -Deletion is less flexible; the only operation is to delete an entire list. +the "head" of the list, a formal location before the first list item.) +Deletion is less flexible; the only operation is to delete an entire list. (There's no reason not to provide finer-grain deletion mechanisms except that it's not clear how to protect against stale pointers efficiently, except by voiding the entire collection of pointers into a list.) @@ -1214,7 +1250,7 @@

        2.9.3. Editing

        The graphical score shown above can be edited by dragging breakpoints, or by adding and deleting them, using mouse clicks. Also, entire objects or -collections of them may be copied, pasted, and dragged around the screen. +collections of them may be copied, pasted, and dragged around the screen. Alternatively, there is an editable (or computer generate-able or parse-able) text representation for the data, which may be seen or changed in a dialog window or read and written to external text files. @@ -1278,7 +1314,7 @@

        2.9.4. Limitations



        next chapter
        - back to table of contents + back to table of contents

        @@ -1286,4 +1322,3 @@

        2.9.4. Limitations

        - diff --git a/pd/doc/1.manual/x4.htm b/pd/doc/1.manual/x4.htm index 956e6d521..56c1ff0f6 100644 --- a/pd/doc/1.manual/x4.htm +++ b/pd/doc/1.manual/x4.htm @@ -25,7 +25,7 @@

        Pd Manual chapter 4: externals

        back to table of contents

        -

        +

        4. Externals

        @@ -89,79 +89,238 @@

        4.1.2.1. Compiled objects:

        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: - +instance: + - - - - + + + + + + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
        Operating SystemCPU-architecturefilename
        OS CPU-architecture float size filename
        Linuxunspecified -(any architecture)my_lib.pd_linux
        Linuxi386 (Intel/AMD 32bit)my_lib.l_i386
        Linuxamd64 (Intel/AMD 64bit)my_lib.l_amd64
        Linuxarm (e.g. RaspberryPi)my_lib.l_arm
        Linuxarm64my_lib.l_arm64
        macOSunspecified -(any architecture)my_lib.pd_darwin
        macOSfat (multiple archs)my_lib.d_fat
        macOSPowerPCmy_lib.d_ppc
        macOSi386 (Intel 32bit)my_lib.d_i386
        macOSamd64 (Intel 64bit)my_lib.d_amd64
        macOSarm64 (Apple Silicon)my_lib.d_arm64
        Windowsunspecified -(any architecture)my_lib.dll
        Windowsi386 (Intel/AMD 32bit)my_lib.m_i386
        Windowsamd64 (Intel/AMD 64bit)my_lib.m_amd64
        Linux unspecified (any architecture) 32my_lib.pd_linux
        ‘’ i386 (Intel/AMD 32bit) 32my_lib.l_i386
        ‘’ ‘’ 32my_lib.linux-i386-32.so
        ‘’ ‘’ 64my_lib.linux-i386-64.so
        ‘’ amd64 (Intel/AMD 64bit) 32my_lib.l_amd64
        ‘’ ‘’ 32my_lib.linux-amd64-32.so
        ‘’ ‘’ 64my_lib.linux-amd64-64.so
        ‘ arm (e.g. RaspberryPi) 32my_lib.l_arm
        ‘’ ‘’ 32my_lib.linux-arm-32.so
        ‘’ ‘’ 64my_lib.linux-arm-64.so
        ‘’ arm64 32my_lib.l_arm64
        ‘’ ‘’ 32my_lib.linux-arm64-32.so
        ‘’ ‘’ 64my_lib.linux-arm64-64.so
        macOS unspecified (any architecture) 32my_lib.pd_darwin
        ‘’ fat (multiple archs) 32my_lib.d_fat
        ‘’ ‘’ 32my_lib.darwin-fat-32.dylib
        ‘’ ‘’ 64my_lib.darwin-fat-64.dylib
        ‘’ PowerPC 32my_lib.d_ppc
        ‘’ ‘’ 32my_lib.darwin-ppc-32.dylib
        ‘’ ‘’ 64my_lib.darwin-ppc-64.dylib
        ‘’ i386 (Intel 32bit) 32my_lib.d_i386
        ‘’ ‘’ 32my_lib.darwin-i386-32.dylib
        ‘’ ‘’ 64my_lib.darwin-i386-64.dylib
        ‘’ amd64 (Intel 64bit) 32my_lib.d_amd64
        ‘’ ‘’ 32my_lib.darwin-amd64-32.dylib
        ‘’ ‘’ 64my_lib.darwin-amd64-64.dylib
        ‘’ arm64 (Apple Silicon) 32my_lib.d_arm64
        ‘’ ‘’ 32my_lib.darwin-arm64-32.dylib
        ‘’ ‘’ 64my_lib.darwin-arm64-64.dylib
        Windows unspecified (any architecture) 32my_lib.dll
        ‘’ i386 (Intel/AMD 32bit) 32my_lib.m_i386
        ‘’ ‘’ 32my_lib.windows-i386-32.dll
        ‘’ ‘’ 64my_lib.windows-i386-64.dll
        ‘’ amd64 (Intel/AMD 64bit) 32my_lib.m_amd64
        ‘’ ‘’ 32my_lib.windows-amd64-32.dll
        ‘’ ‘’ 64my_lib.windows-amd64-64.dll
        - +

        4.1.2.2. Abstractions:

        You can have a Pd patch behave like an object by loading it into other @@ -224,8 +383,7 @@

        Wrapping up Part 1)

        4.2. Installing External Objects and Libraries

        - - +

        Installing externals in Pd is quite simple, all you need to do is download @@ -589,7 +747,7 @@

        4.5. Search order for loading objects



        next chapter
        - back to table of contents + back to table of contents

        diff --git a/pd/doc/1.manual/x5.htm b/pd/doc/1.manual/x5.htm index d160d393b..49e767e06 100644 --- a/pd/doc/1.manual/x5.htm +++ b/pd/doc/1.manual/x5.htm @@ -30,14 +30,70 @@

        Pd Manual chapter 5: current status

        5.1. release notes

        +

        ------------------ 0.54-1 ------------------------------ + +

        Fixes a compatibility problem with MacOS 14. + +

        Numerous bug fixes and documentation updates. + +

        ------------------ 0.54-0 ------------------------------ + +

        Multichannel audio signals are supported for many objects. They may be created +or split into component channels using the new [snake~] object. Supported obects +include stateless tilde objects such as [abs~], [sqrt~], [rsqrt~], [wrap~], [exp~], +[cos~], [ftom~], [mtof~], [dbtorms~], [rmstodb~], [dbtopow~], [powtodb~], [clip~], +[+], [-], [*], [/], [max~], [min~], [log~], [pow~], [fft~], ifft~], [rfft~], [rifft~] and +[lrshift~]. The [send~]/[receive~], [throw~]/[catch~] also manage multichannel signals and +[tabwrite~], [tabread~], [tabread4~] and [tabplay~] now deal with more than one array and +multichannel signals. + +

        The [inlet~]/[outlet~] objects are not always stateless but it was judged necessary to +support them. The [clone] object received special attention since it might be desirable to +distribute multichannel signals among the cloned patches or to pass them directly into all +copies as multichannel inputs and outputs. The [adc~] object can also generate multichannel +signals from the input card, while [dac~] can directly manage a multichannel signal and +distribute to different channels. + +

        The [clone] object takes a message to change the number of copies. So now Pd +is useful as a non-real-time software synthesizer. Changing the number of +copies will cause massive reinitialization and memory allocation and should not +be used during preformance, only during setup. + +

        The [sigmund~] object got some new optimizations and has more parameters that can be +tuned for a particular instrument. A longstanding octave-jumping problem has been +partially addressed, and anyway, a new output type offers even/odd balance so +that a synth can play in unison with an instrument with very few octave jumps +by coherently mixing both possible octaves. + +

        The [lop~] object can now also take a signal to set rolloff frequency, but the same +slightly faster algorithm is used if you have a scalar input instead. + +

        There are new methods for the [file] object by IOhannes, namely "cwd", "patchpath", +"normalize" and "isabsolute". + +

        The 64-bit windows build uses the lower-latency WASAPI audio system in place +of the older MMIO. This therefore only runs on Windows 7 and newer. The 32-bit version +can still run all the way back to Windows XP. + +

        There's a new design for the stereo [output~] abstraction in the 'extra' library +by Alexandre Porres. This is widely used in the documentation and now has a slider +to set the volume and you can also use a number box. It can also distribute a mono +input to both channels. + +

        The Windows installer can be run on non-admin users. + +

        Improved settings dialog window. + +

        As usual, countless bug fixes and miscellaneous improvements. +

        ------------------ 0.53-2 ------------------------------ -update portaudio to version v19.7.0 to fix macintosh hanging problem +

        Update portaudio to version v19.7.0 to fix macintosh hanging problem.

        ------------------ 0.53-1 ------------------------------

        Bug fixes, mostly from Iohannes concerning iemguis regression bugs because of -the cleanup/rewrite for 0.53. Also more documentation by Alexandre Porres. +the cleanup/rewrite for 0.53. Also more documentation updates by Alexandre Porres.

        ------------------ 0.53-0 ------------------------------ diff --git a/pd/doc/1.manual/x6-a.htm b/pd/doc/1.manual/x6-a.htm index 21d5ea551..477afa004 100644 --- a/pd/doc/1.manual/x6-a.htm +++ b/pd/doc/1.manual/x6-a.htm @@ -9,7 +9,7 @@ - + @@ -40,7 +40,7 @@

        Pd macOS app

        The basic layout is:

        -
        Pd-0.47-1.app/Contents
+
        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
@@ -51,7 +51,8 @@ 
        Pd macOS app
        
     /font     <- included fonts
     /po       <- text translation files
     /src      <- Pd source header files
-    /tcl      <- Pd GUI scripts
        
+    /tcl      <- Pd GUI scripts
+

        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 @@ -70,38 +71,38 @@

        App Bundle Helpers

        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:

        -
        mac/tcltk-wish.sh --arch i386 8.6.6
+
        mac/tcltk-wish.sh --arch i386 8.6.6
 mac/osx-app.sh --wish Wish-8.6.6.app 0.47-1
-
        
+

        Both osx-app.sh & tcltck-wish.sh have extensive help output using the –help commandline option:

        -
        mac/osx-app.sh --help
+
        mac/osx-app.sh --help
 mac/tcltk-wish.sh --help
-
        
+

        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:

        -
        mac/osx-app.sh 0.47-1
-
        +
        mac/osx-app.sh 0.47-1
+

        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.

        -

        A pre-built universal (32/64 bit) Tk 8.6.10 Wish with patches applied is +

        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:

        -
        # build Pd-0.47-1.app using Tk 8.6 installed to the system
+
        # 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
-
        
+

        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 @@ -110,28 +111,28 @@

        App Bundle Helpers

        The tcltk-wish.sh script automates building a Wish.app with embedded Tcl/Tk, either from the release distributions or from a git clone:

        -
        # build Wish-8.6.6.app with embedded Tcl/Tk 8.6.6
+
        # 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
-
        
+

        You can also specify which architectures to build (32 bit, 64 bit, or both):

        -
        # build 32 bit Wish-8.6.6.app with embedded Tcl/Tk 8.6.6
+
        # 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
-
        
+

        Once your custom Wish.app is built, you can use it as the .app source for osx-app.sh with the -w/–wish option:

        -
        # build Pd with a custom Tcl/Tk 8.6.6 Wish
+
        # build Pd with a custom Tcl/Tk 8.6.6 Wish
 mac/osx-app.sh -w Wish-8.6.6.app
-
        
+

        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 @@ -168,16 +169,16 @@

        Supplementary Build Scripts

        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:

        -
        ./build-macosx 0.47-1
-
        +
        ./build-macosx 0.47-1
+

        If all goes well, you’ll soon see a new app appear named Pd-0.47-1.app.

        If you want to build a 64 bit Pd, perform the same steps and use the build-mac64 script:

        -
        ./build-mac64 0.47-1
-
        +
        ./build-mac64 0.47-1
+

        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

        @@ -198,15 +199,15 @@

        Preferences

        The files themselves live in your user home folder and use the .plist extension:

        -
        ~/Library/Preferences/org.puredata.pd.plist
+
        ~/Library/Preferences/org.puredata.pd.plist
 ~/Library/Preferences/org.puredata.pd.pd-gui.plist
-
        
+

        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:

        -
        # print the contents of the core settings
+
        # print the contents of the core settings
 defaults read org.puredata.pd
 
 # delete the current GUI settings
@@ -214,7 +215,7 @@ 
        Preferences
        
 
 # set the startup flag in the core settings
 defaults write org.puredata.pd -array-add flags '-lib Gem'
-
        
+

        Some important per-application settings required by the GUI include:

        @@ -223,10 +224,11 @@

        Preferences

      2. NSQuitAlwaysKeepsWindows: false, disables default 10.7+ window state saving
      3. ApplePressAndHoldEnabled: false, disables character compose popup, enables key repeat for all keys
        4. +
      4. NSRequiresAquaSystemAppearance: true, disables dark mode for Pd GUI on 10.14+
        5. -

        These are set in tcl/pd_guiprefs.tcl.

        +

        These are set in tcl/pd_guiprefs.tcl.

        Code Signing

        @@ -236,7 +238,105 @@

        Code Signing

        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.

        -
        + +

        Privacy Permissions

        + +

        macOS 10.14 introduced system privacy permissions for actions applications can +undertake on a user account, such as accessing files or reading microphone or +camera input. When an application is started for the first time and tries to +access something that is covered by the privacy settings, a permissions prompt +is displayed by the system requesting access. The action is then allowed or +denied and this setting is saved and applied when the application is run again +in the future.

        + +

        As of macOS 10.15, running Pd will request access for the following:

        + +
          +
        • Files and Folders: Documents
          • +
        • Files and Folders: Desktop
          • +
        • Microphone
          • +
        + + +

        Additionally, using an external such as Gem for camera input will request +access to the Camera.

        + +

        The current permissions can be changed in Privacy panel in System Preferences. +They can also be reset on the commandline using the “tccutil” command and the +Pd .app bundle id:

        + +
        # reset Pd's Microphone privacy setting
+tccutil reset Microphone org.puredata.pd.pd-gui
+
+# reset all of Pd's privacy settings
+tccutil reset All org.puredata.pd.pd-gui
+
        + +

        Font Issues with macOS 10.15+

        + +

        macOS 10.15 furthered changes to font rendering begin with 10.14 with the weird +result that Pd’s default font, DejaVu Sans Mono, renders thin and closer +together than system fonts. This results in objects on the patch canvas that are +longer their inner text and text selection positioning is off.

        + +

        To remedy this for now, Pd 0.51-3 changed Pd’s default font for macOS to Menlo +which is included with the system since 10.6. Menlo is based on Bitstream Vera +Mono and DejaVu Sans Mono, so there should be no issues with patch sizing or +positioning.

        + +

        Dark Mode

        + +

        Pd currently disables Dark Mode support by setting the +NSRequiresAquaSystemAppearance key to true in both the app bundle’s Info.plist +and the GUI defaults preference file. This restriction may be removed in the +future once Dark Mode is handled in the GUI.

        + +

        Debugging Releases

        + +

        On macOS 10.15+, apps must be signed with an entitlement to allow debugging. +This is good for security, but bad if you want to run Pd in lldb to figure out +why your custom external is crashing.

        + +

        To make this work, the entitlement can be added to an existing Pd release .app +bundle using the codesign command in Terminal (steps by Pierre Alexandre +Tremblay):

        + +
          +
        • Extract the current Pd entitlements from the internal pd binary:
          • +
        + + +
            codesign -d /Applications/Pd-0.53-2.app/Contents/Resources/bin/pd \
+    --entitlements :~/Desktop/pd-entitlements.xml
+
        + +
          +
        • Edit pd-entitlements.xml on your Desktop, add the following key, and save:
          • +
        + + +
            <key>com.apple.security.get-task-allow</key>
+    <true/>
+
        + +
          +
        • Re-sign the pd binary with the updated entitlements:
          • +
        + + +
            codesign -s - --deep --force --options=runtime \
+    --entitlements ~/Desktop/pd-entitlements.xml \
+    /Applications/Pd-0.53-2.app/Contents/Resources/bin/pd
+
        + +

        Now Pd can be run with lldb using:

        + +
        lldb /Applications/Pd-0.53-2.app/Contents/Resources/bin/pd
+
        + +

        Note: Re-signing using an ad-hoc identifier will work on the development system, + but running the Pd .app bundle on another system will result in security + warnings as the original signature and notarization are invalid.

        back to ch6 back to table of contents


        @@ -247,4 +347,4 @@

        Code Signing

        - + \ No newline at end of file diff --git a/pd/doc/1.manual/x6-c.htm b/pd/doc/1.manual/x6-c.htm new file mode 100644 index 000000000..6edacfd70 --- /dev/null +++ b/pd/doc/1.manual/x6-c.htm @@ -0,0 +1,150 @@ + + + + + + +Pd Manual 6 + + + + + + + +
        + +
        + +
        + +

        back to ch6 back to table of contents

        + +

        6.3.1. BSD

        + +

        Building Pd for the various BSD variants is similar to the Linux way. +The major difference is the used package manager (and the names of the packages), +you’ll want to install.

        + +

        FreeBSD

        + +

        (Tested on FreeBSD-13)

        + +

        Install the core build requirements:

        + +
        sudo pkg install gcc automake autoconf libtool gettext gmake
+
        + +

        You may install one (or more) libraries (depending on your needs). +It seems that with FreeBSD-13, there are ALSA and JACK packages available:

        + +
        sudo pkg install alsa-lib jackit
+
        + +

        Once your build system is set up, you can follow the general autotools build +steps to build Pd, but make sure to use gmake (aka “GNU make”). +The ordinary BSD make will not suffice!

        + +
        ./autogen.sh
+./configure --deken-os=FreeBSD MAKE=gmake
+gmake
+
+sudo gmake install
+
        + +

        OpenBSD

        + +

        (Tested on OpenBSD-7)

        + +

        Install the core build requirements:

        + +
        sudo pkg_add gcc automake autoconf libtool gettext-tools gmake
+
        + +

        (If there are multiple versions for one or more of the packages, pick your favourite or the newest one).

        + +

        You may install one (or more) libraries (depending on your needs). +It seems that with OpenBSD-7, there are only JACK packages available:

        + +
        sudo pkg_add jack
+
        + +

        By default, OpenBSD installs all its packages into /usr/local/, +but the compiler does not look for headers resp. libraries in this directory. +We can instruct autotools to automatically consider these directories +by creating a file ‘/usr/local/share/config.site’:

        + +
        cat | sudo tee /usr/local/share/config.site>/dev/null << EOF
+CPPFLAGS="-I/usr/local/include \$CPPFLAGS"
+LDFLAGS="-L/usr/local/lib \$LDFLAGS"
+EOF
+
        + +

        Also, because OpenBSD allows to coinstall multiple versions of the autotools (with no “default”), +we must specify which version we want to use:

        + +
        export AUTOCONF_VERSION=$(ls -S /usr/local/bin/autoconf-* | sed -e 's|.*-||' | sort -n | tail -1)
+export AUTOMAKE_VERSION=$(ls -S /usr/local/bin/automake-* | sed -e 's|.*-||' | sort -n | tail -1)
+
        + +

        Now that your build system is set up, you can follow the general autotools build +steps to build Pd, but make sure to use gmake (aka “GNU make”). +The ordinary BSD make will not suffice!

        + +
        ./autogen.sh
+./configure --deken-os=OpenBSD --enable-jack MAKE=gmake
+gmake
+
+sudo gmake install
+
        + +

        NetBSD

        + +

        (Tested on NetBSD-9)

        + +

        Install the core build requirements:

        + +
        sudo pkgin install gcc automake autoconf libtool gettext-tools gmake
+
        + +

        You may install one (or more) libraries (depending on your needs). +It seems that with NetBSD-9, there are JACK and ALSA packages available, +but the ALSA packages seem to be broken. OSS appears to be built-in.

        + +
        sudo pkgin install jack
+
        + +

        By default, NetBSD installs all its packages into /usr/pkg/, +but the compiler does not look for headers resp. libraries in this directory. +We can instruct autotools to automatically consider these directories +by creating a file ‘/usr/pkg/share/config.site’:

        + +
        cat | sudo tee /usr/pkg/share/config.site>/dev/null << EOF
+CPPFLAGS="-I/usr/pkg/include \$CPPFLAGS"
+LDFLAGS="-L/usr/pkg/lib -Wl,-R/usr/pkg/lib \$LDFLAGS"
+EOF
+
        + +

        Now that your build system is set up, you can follow the general autotools build +steps to build Pd, but make sure to use gmake (aka “GNU make”). +The ordinary BSD make will not suffice!

        + +
        ./autogen.sh
+./configure --deken-os=NetBSD --prefix=/usr/pkg --disable-alsa --enable-jack MAKE=gmake
+gmake
+
+sudo gmake install
+
        + +
        +

        back to ch6 back to table of contents

        +
        +
        +
        + +
        + + + + + diff --git a/pd/doc/1.manual/x6.htm b/pd/doc/1.manual/x6.htm index 3582aab0a..7199980db 100644 --- a/pd/doc/1.manual/x6.htm +++ b/pd/doc/1.manual/x6.htm @@ -9,7 +9,7 @@ - + @@ -26,7 +26,7 @@

        Pd Manual chapter 6: Installing from source.

        back to table of contents

        -

        +

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

        @@ -118,6 +118,12 @@

        6.2. Autotools Build (recommended)

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

        If you need to run Pd through a debugger (like gdb), you can +build Pd with debugging symbols using the "--enable-debug" flag. + +

        # build Pd with debugging information
+./configure --enable-debug
        +

        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:

        # build 32 bit Pd
@@ -196,6 +202,10 @@ 
        6.3 Linux & BSD
        
 
        Most distributions come with Tcl/Tk installed, so you should be able to run Pd after it is built.
        
 
        Once your build system is set up, you can follow the general autotools build steps to build Pd.
        
 
+
        For more information and how to build on BSD see: 
        
+
+
        Show more on BSD
        
+
 
        6.4. macOS
        
 
 
        macOS is built on top of a BSD system and the bash commandline can be accessed with the Terminal application in the /Applications/Utility directory.
        
@@ -310,7 +320,7 @@ 
        6.5. Windows
        
 pacman -S mingw-w64-i686-toolchain mingw-w64-i686-clang \
           make autoconf automake libtool \
           mingw-w64-i686-gettext
        - +

        Install git if you want to clone the Pd sources from Github, etc:

        pacman -S git
        @@ -360,9 +370,9 @@

        6.5. Windows

        6.6. Double precision

        -

        As of Pd 0.51-0 you can compile a "Double precision" Pd. On the autotools do:

        +

        As of Pd 0.54-0 you can compile a "Double precision" Pd (AKA: Pd64). On the autotools do:

        -
        ./configure CPPFLAGS="-DPD_FLOATSIZE=64"
        +
        ./configure --with-floatsize=64

        6.7. Other flags

        @@ -459,7 +469,7 @@

        6.10. Reporting Bugs



        - back to table of contents + back to table of contents