diff options
| -rw-r--r-- | README.md | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..43f217c --- /dev/null +++ b/README.md @@ -0,0 +1,138 @@ += 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 |