path: root/README.md

= 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