aboutsummaryrefslogtreecommitdiff

= Ybuild – it comes after X but before Z and is not K

Ybuild is intended to be a set of Makefiles inspired by Kbuild for hassle free building of complex projects.

== Conceptual differences to Kbuild

The main conceptual difference is, that Ybuild shall treat multiple product build configurations as first class citizens.

This is in contrast to Kbuild, which is aimed at building a single target (the Linux kernel -- kernel modules are treated as constituents of that single target, that are just linked in later at runtime). User space applications are second class citizens in Kbuild.

== Structure of a (private) project that influences design decisions

Ybuild's design ATM is influenced by the structure of a private, not to be published project of the author, in development at the time of writing this README (Dec 2020). It is hence strongly suggested to understand this structure, before working on or with Ybuild.

The general code structure layout is outlined to strictly reflect the relative installation destinations of the targets. The preferred layout loosly reflects the directory layout of the LSB with category directories, later on referenced by ${CATEGORY}:

  • ./bin/${PROJECT} – user facing executables.
  • ./share/${PROJECT} – non executable runtime data.
  • ./lib/${PROJECT} – code shared among executables of this project.
  • ./libexec/${PROJECT} – internally used executables.

The reasoning here is, that installation of the final product is as simple as extracting the release archive in one of the usual destinations (/opt/${PROJECT}, /usr, /usr/local, C:\Program Files\${PROJECT}, you get the idea).

All source inputs that go into the creation of a release package go into ${BASE}/src.

Contents of ./share may be turned into target dependent intermediaries, for example by wrapping data into object files to link them into the binaries that require them.

Sources for build helper tools, that will not end up in the release package proper are placed inside ${BASE}/src. Following the general category structure is recommended, but not required.

Intermediary build steps go into ${BUILD}/${TARGET}/${CATEGORY} If a build intermediary is target independent (think graphical resources, UI description files, etc.) it goes into ${BUILD}/....

The final results are linked and packaged together into ${INSTALL}/${TARGET}/${CATEGORY}/${PROJECT}.

=== Example project structure and outline of the build process.

1st non executable runtime resources are processed into distribution form. For example textures may be compressed (in a GPU ingestible, compressed format):

${BASE}/share/${PROJECT}/textures/iconsheet.png${BUILD}/share/${PROJECT}/textures/iconsheet.dxtc

${BASE}/share/${PROJECT}/icons/hicolor/scalable/apps/example.svg${BUILD}/share/${PROJECT}/icons/hicolor/32x32/apps/example.png

${BUILD}/share/${PROJECT}/icons/hicolor/32x32/apps/example.png${BUILD}/share/${PROJECT}/icons/hicolor/32x32/apps/example.dxct

Some of these resourced may be wrapped in an object file, so that they can be linked right into the executable binary:

${BUILD}/share/${PROJECT}/textures/iconsheet.dxtc${BUILD}/${TARGET}/share/${PROJECT}/textures/iconsheet.dxtc.o

${BUILD}/share/${PROJECT}/icons/hicolor/32x32/apps/example.dxct${BUILD}/share/${PROJECT}/icons/hicolor/32x32/apps/example.dxct.o

Sources of executable targets are compiled:

${BASE}/src/lib/${PROJECT}/libexample-gfx.cc${BUILD}/${TARGET}/lib/${PROJECT}/libexample-gfx.o

${BASE}/src/libexec/${PROJECT}/example-helper-auxiliary.cc${BUILD}/${TARGET}/libexec/${PROJECT}/example-helper-auxiliary.o

${BASE}/src/libexec/${PROJECT}/example-helper-main.cc${BUILD}/${TARGET}/libexec/${PROJECT}/example-helper-main.o

${BASE}/src/bin/${PROJECT}/example-ui.cc${BUILD}/${TARGET}/bin/${PROJECT}/example-ui.o

${BASE}/src/bin/${PROJECT}/example-main.cc${BUILD}/${TARGET}/bin/${PROJECT}/example-main.o

Intermediary files are linked/copied into the installation release directory; take note, that the final executables are not considered intermediaries that shall be created in the build directory first. In the same way files that go into the installation destination without intermediary processing are copied there directly from source:

${BASE}/share/${PROJECT}/icons/hicolor/scalable/apps/example.svg${INSTALL}/share/${PROJECT}/icons/hicolor/scalable/apps/example.svg

${BUILD}/share/${PROJECT}/icons/hicolor/32x32/apps/example.png${INSTALL}/share/${PROJECT}/icons/hicolor/32x32/apps/example.png

The 48x48 icon in this example is not linked into any binary and is not generated from any intermediaries, so it's created directly from the source.

${BASE}/share/${PROJECT}/icons/hicolor/scalable/apps/example.svg${INSTALL}/share/${PROJECT}/icons/hicolor/48x48/apps/example.png

In this example the libexample-gfx shared library also contains the iconsheet:

${BUILD}/${TARGET}/share/${PROJECT}/textures/iconsheet.dxtc.o ${BUILD}/${TARGET}/lib/${PROJECT}/libexample-gfx.o${INSTALL}/${TARGET}/lib/${PROJECT}/libexample-gfx.{so,dll}

The example-helper links just against libexample-gfx but carries no own resources

${BUILD}/${TARGET}/libexec/${PROJECT}/example-helper-auxiliary.o ${BUILD}/${TARGET}/libexec/${PROJECT}/example-helper-main.o${INSTALL}/${TARGET}/libexec/${PROJECT}/example{,.exe}

Similarly the example application will contain its DXCT compressed icon:

${BUILD}/share/${PROJECT}/icons/hicolor/32x32/apps/example.dxct.o${BUILD}/${TARGET}/bin/${PROJECT}/example-ui.o${BUILD}/${TARGET}/bin/${PROJECT}/example-main.o${INSTALL}/${TARGET}/lib/${PROJECT}/libexample-gfx.{so,dll}${INSTALL}/${TARGET}/bin/${PROJECT}/example{,.exe}`

== Q&A / Rationale