258 lines
8.5 KiB
Markdown
258 lines
8.5 KiB
Markdown
pd-lib-builder cheatsheet
|
|
=========================
|
|
|
|
# Creating special builds
|
|
|
|
## Building for non-native platform
|
|
|
|
Using pd-lib-builder >=0.6.0 we can define variable `PLATFORM` to specify a
|
|
target triplet for cross-compilation. Assuming a W32 package for Pd is unzipped
|
|
into path `${PDWIN32}`, to build for Windows 32 bit:
|
|
|
|
make PLATFORM=i686-w64-mingw32 PDDIR="${PDWIN32}"
|
|
|
|
#### Older pd-lib-builder versions
|
|
|
|
Using pd-lib-builder < 0.6.0, in the absence of variable `PLATFORM`, you would
|
|
instead override variables `system`, `target.arch`, `CC` and / or `CXX`,
|
|
`STRIP`. Example:
|
|
|
|
make system=Windows target.arch=i686 CC=i686-w64-mingw32-gcc STRIP=i686-w64-mingw32-strip PDDIR="${PDWIN32}"
|
|
|
|
#### Toolchains
|
|
|
|
To build for non-native OS and/or architecture you need a cross toolchain. On
|
|
Linux such toolchains are relatively easy to get. For example Debian Buster
|
|
amd64 provides them for the following platforms (install g++ with dependencies
|
|
for a given platform to get the whole toolchain):
|
|
|
|
- `arm-linux-gnueabihf`
|
|
- `aarch64-linux-gnu`
|
|
- `i686-linux-gnu`
|
|
- `i686-w64-mingw32` and `x86_64-w64-mingw32` (install `mingw-w64`)
|
|
|
|
Cross toolchains for OSX/MacOS are not generally distributed. Project
|
|
`osxcross` from Thomas Poechtraeger can create them for Linux.
|
|
|
|
## Universal binaries on macOS
|
|
|
|
The compiler, by default, builds for the native architecture of the build
|
|
machine. To make a "universal" multi-arch build, specify the desired
|
|
archtectures on the command line using the "arch" pd-lib-builder Makefile
|
|
variable.
|
|
|
|
For example, to build a "fat" external for both 64-bit Intel and Arm (Apple
|
|
Silicon):
|
|
|
|
make arch="x86_64 arm64"
|
|
|
|
If the build is successful, the compiled architectures in the built external can
|
|
be confirmed via the `file` command:
|
|
|
|
~~~sh
|
|
% file vbap.pd_darwin
|
|
vbap.pd_darwin: Mach-O universal binary with 2 architectures: [x86_64:Mach-O 64-bit bundle x86_64] [arm64:Mach-O 64-bit bundle arm64]
|
|
vbap.pd_darwin (for architecture x86_64): Mach-O 64-bit bundle x86_64
|
|
vbap.pd_darwin (for architecture arm64): Mach-O 64-bit bundle arm64
|
|
~~~
|
|
|
|
Note: The available architectures depend on which macOS version & command line
|
|
tools/Xcode combination the build system has. For example, any newer macOS
|
|
10.15+ will support both x86_64 (Intel 64-bit) and arm64 (Apple Silicon) while
|
|
OSX 10.6 - macOS 10.14 can build for x86_64 and i386 (Intel 32-bit).
|
|
|
|
## Building double-precision externals
|
|
|
|
At the time of writing (2023-07-06) there is no official Pd that supports
|
|
double-precision numbers yet.
|
|
However, if you do get hold of an experimental double-precision Pd, you can
|
|
easily build your externals for 64-bit numbers, by passing `floatsize=64`
|
|
as an argument to `make`.
|
|
Starting with Pd>=0.54, double precision externals use different extensions
|
|
from traditional (single-precision) externals.
|
|
The extension consists of the OS ("linux", "darwin", "windows"), the CPU
|
|
architecture ("amd64" (x86_64), "i386" (x86), "arm64",...) and the floatsize
|
|
in bits ("64" for double-precision), followed by the system's native extension
|
|
for dynamic libraries (".dll" on Windows, ".so" on macOS/Linux/un*xes).
|
|
As of pd-lib-builder==0.7.0, you have to manually pass this extension:
|
|
|
|
make floatsize=64 extension=windows-amd64-64.so
|
|
make floatsize=64 extension=linux-arm64-64.so
|
|
make floatsize=64 extension=darwin-fat-64.so arch="x86_64 arm64"
|
|
|
|
|
|
# Project management
|
|
|
|
In general it is advised to put the `Makefile.pdlibbuilder` into a separate
|
|
subdirectory (e.g. `pd-lib-builder/`).
|
|
This makes it much easier to update the `Makefile.pdlibbuilder` later
|
|
|
|
You *should* also use a variable to the actual path of the Makefile.pdlibbuilder
|
|
(even if you keep it in the root-directory), as this allows easy experimenting
|
|
with newer (or older) (or site-specific) versions of the pd-lib-builder
|
|
Makefile.
|
|
|
|
~~~make
|
|
PDLIBBUILDER_DIR=pd-lib-builder/
|
|
include $(PDLIBBUILDER_DIR)/Makefile.pdlibbuilder
|
|
~~~
|
|
|
|
## Keeping pd-lib-builder up-to-date
|
|
|
|
### `git subtree`
|
|
|
|
With git-subtrees, you make the pd-lib-builder repository (or any other
|
|
repository for that matter) part of your own repository - with full history and
|
|
everything - put nicely into a distinct subdirectory.
|
|
|
|
Support for *manipulating* subtrees has been added with Git-v1.7.11 (May 2012).
|
|
The nice thing however is, that from "outside" the subtree is part of your
|
|
repository like any other directory. E.g. older versions of Git can clone your
|
|
repository with the full subtree (and all it's history) just fine.
|
|
You can also use git-archive to make a complete snapshot of your repository
|
|
(including the subtree) - nice, if you e.g. want self-contained downloads of
|
|
your project from git hosting platforms (like Github, Gitlab, Bitbucket,...)
|
|
|
|
In short, `git subtree` is the better `git submodule`.
|
|
|
|
So here's how to do it:
|
|
|
|
#### Initial setup/check-out
|
|
|
|
This will create a `pd-lib-builder/` directory containing the full history of
|
|
the pd-lib-builder repository up to its release `v0.5.0`
|
|
|
|
~~~sh
|
|
git subtree add --prefix=pd-lib-builder/ https://github.com/pure-data/pd-lib-builder v0.5.0
|
|
~~~
|
|
|
|
This will automatically merge the `pd-lib-builder/` history into your current
|
|
branch, so everything is ready to go.
|
|
|
|
#### Cloning your repository with the subtree
|
|
|
|
Nothing special, really.
|
|
Just clone your repository as always:
|
|
|
|
~~~sh
|
|
git clone https://git.example.org/pd/superbonk~.git
|
|
~~~
|
|
|
|
#### Updating the subtree
|
|
|
|
Time passes and sooner or later you will find, that there is a shiny new
|
|
pd-lib-builder with plenty of bugfixes and new features.
|
|
To update your local copy to pd-lib-builder's current `master`, simply run:
|
|
|
|
~~~sh
|
|
git subtree pull --prefix pd-lib-builder/ https://github.com/pure-data/pd-lib-builder master
|
|
~~~
|
|
|
|
#### Pulling the updated subtree into existing clones
|
|
|
|
Again, nothing special.
|
|
Just pull as always:
|
|
|
|
~~~sh
|
|
git pull
|
|
~~~
|
|
|
|
#### Further reading
|
|
|
|
More on the power of `git subtree` can be found online
|
|
- https://medium.com/@v/git-subtrees-a-tutorial-6ff568381844
|
|
- https://www.atlassian.com/blog/git/alternatives-to-git-submodule-git-subtree
|
|
- ...
|
|
|
|
### ~~`git submodule`~~ [DISCOURAGED]
|
|
|
|
#### Initial setup/check-out
|
|
|
|
To add a new submodule to your repository, just run `git submodule add` and
|
|
commit the changes:
|
|
|
|
~~~sh
|
|
git submodule add https://github.com/pure-data/pd-lib-builder
|
|
git commit .gitmodules pd-lib-builder/ -m "Added pd-lib-builder as git-submodule"
|
|
~~~
|
|
|
|
#### Cloning your repository with the submodule
|
|
|
|
When doing a fresh clone of your repository, pass the `--recursive` option to
|
|
automatically fetch all submodules:
|
|
|
|
~~~sh
|
|
git clone --recursive https://git.example.org/pd/superbonk~.git
|
|
~~~
|
|
|
|
If you've cloned non-recursively, you can initialize and update the submodules
|
|
manually:
|
|
|
|
~~~sh
|
|
git submodule init
|
|
git submodule update
|
|
~~~
|
|
|
|
#### Updating the submodule
|
|
|
|
Submodules are usually fixed to a given commit in their repository.
|
|
To update the `pd-lib-builder` submodule to the current `master` do something
|
|
like:
|
|
|
|
~~~sh
|
|
cd pd-lib-builder
|
|
git checkout master
|
|
git pull
|
|
cd ..
|
|
git status pd-lib-builder
|
|
git commit pd-lib-builder -m "Updated pd-lib-builder to current master"
|
|
~~~
|
|
|
|
#### Pulling the updated submodule into existing clones
|
|
|
|
After you have pushed the submodule updates in your repository, other clones of
|
|
the repository can be updated as follows:
|
|
|
|
~~~sh
|
|
git pull
|
|
~~~
|
|
|
|
The above will make your repository aware, that the submodule is out-of-sync.
|
|
|
|
~~~sh
|
|
$ LANG=C git status pd-lib-builder
|
|
On branch master
|
|
Your branch is up to date with 'origin/master'.
|
|
|
|
Changes not staged for commit:
|
|
(use "git add <file>..." to update what will be committed)
|
|
(use "git checkout -- <file>..." to discard changes in working directory)
|
|
|
|
modified: pd-lib-builder (new commits)
|
|
$
|
|
~~~
|
|
|
|
In order to sync the submodule to the correct commit, run the following:
|
|
|
|
~~~sh
|
|
git submodule update
|
|
~~~
|
|
|
|
#### Drawbacks
|
|
|
|
`git submodule` has a number of drawbacks:
|
|
- it requires special commands to synchronize the submodules, in addition to
|
|
synching your repository.
|
|
- you must make sure to use an URL for the submodule that is accessible to your
|
|
potential users. e.g. using `git@github.com:pure-data/pd-lib-builder` is bad,
|
|
because it requires everybody who wants to checkout your sources to have a
|
|
github-account - even if they could checkout *your* repository anonymously.
|
|
- submodules will be excluded from `git archive`. This means, that if you use a
|
|
mainstream git provider (like Github, GitLab, Bitbucket,...) and make releases
|
|
by creating a `git tag`, the automatically generated zipfiles with the sources
|
|
will lack the submodule - and your users will not be able to compile your
|
|
source code.
|
|
|
|
In general, I would suggest to **avoid** `git submodule`, and instead use the
|
|
better `git subtree` (above).
|