initial README commitHEADmaster

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