mission statement?

[umlaeute]

We've seen a number of bug-reports and PRs (e.g. #74, #69) that are about adapting pd-lib-builder for "modern systems" (mostly macOS, as this is the ecosystem that cares least about backward compatibility), and there has been quite a bit of push-back.

So I think that there is a bit of a discrepancy between what "users" expect from the library, and what its "maintainers" want it to be(come).

I would therefore like to find out what the "mission statement" of pd-lib-builder is, in order to level expectations (and keep frustration low).

Here's a few guiding questions in no particular order (I'm sure I forgot the most important and succinct questions, please add them):

• Who is the target audience?
  e.g.
  • Developers
  • End Users (with a compiler)
  • Package Maintainers
  • ...?
• Which operating systems are supported?
  e.g.
  • Debian/GNU Linux
  • Windows (MSYS2/MinGW)
  • OSX
  • macOS
  • ...?
• Is the use of external dependencies (3rd party libraries) supported?
  e.g.
  • no
  • only things that ship with the base OS
  • things that are installed with the native OS package manager
  • things that are installed by popular package managers for the OS
  • ...?
• How should the library be embedded?
  e.g.
  • a copylib that people are supposed to fork and adjust to their own needs
  • a central reference implementation (where people are supposed to used the latest and greatest)
  • ...?

(The answers above are not answers at all, just examples of what might be answers).

On a less fundamental level:

• What is the relation between the calling Makefile and the Makefile.pdlibbuilder snippet?
  e.g.
  • pd-lib-builder is a build-system that reads a declarative description of the library to build and turns it into a compiled (and usable) library
  • pd-lib-builder is a set of helper-functions to aide in creating a build-system
  • ...?

[katjav]

Makefile.pdlibbuilder could be considered a domain-specific helper makefile, defining a common denominator in makefile systems for pd libraries that use it. Illustrating its relation with a lib makefile:

individual part (lib makefile): defines output files (in abstract sense) and the
 input files and other things that they depend on

(scissors, snip snip <)---------------------------------------------------------

common denominator part (helper makefile): defines output files in literal sense,
 and the rules to make these from the input files, for all platforms where pd can run

The main purpose of this split is to bundle user expertise in a community maintained helper makefile. But what is the scope, the sort of expertise aimed at? That was never explicited. The project's content focuses on platform-specific definitions, and targets for makefile debugging. The first of these aspects has received most attention and contributions. Lib devs and users bundle expertise about their preferred platform in the helper makefile. As a result it provides convenience and hides many complexities.

By providing convenience but not expliciting scope, the pd-lib-builder project may suggest that its interface means to cover everything that a lib makefile or a user thereof could do. But that is not true. Makefile.pdlibbuilder is just part of a makefile that includes it, not a separate program. A lib makefile can do a lot around the helper makefile to resolve lib-specific needs. This may be promoted more loudly, supported with links to real-world examples which already exist to minimize documentation efforts.

I would not be able to define a concise mission statement but could mention my personal view on omissions. What has annoyed me most right from the start is the inability to build out of source directories. This may be mission impossible with a "calculated makefile" like ours and I don't want to think about it anymore. What bothers me most in current practice is that we seem to loose grip on architecture definitions. Increased ambiguity of "fat binary" is just one consequence of Apple's arm64 processor. More serious is (issue #76) that you can't supply both Intel and arm64 optimizations in a single build process, meaning that a fat build should probably be carried out as two builds + lipo for even the simplest lib. Speaking of convenience...