More clarification of the basic data model

beetroot-project · Jul 11, 2019 · f9c01da · f9c01da
1 parent 6b6526a
commit f9c01da
Show file tree

Hide file tree

Showing 14 changed files with 488 additions and 3 deletions.
diff --git a/docs/1TARGET_2INSTANCES.png → docs/about/1TARGET_2INSTANCES.png b/docs/1TARGET_2INSTANCES.png → docs/about/1TARGET_2INSTANCES.png
diff --git a/docs/2TARGETS_2INSTANCES.png → docs/about/2TARGETS_2INSTANCES.png b/docs/2TARGETS_2INSTANCES.png → docs/about/2TARGETS_2INSTANCES.png
diff --git a/docs/2TARGETS_2INSTANCES_compact.png → docs/about/2TARGETS_2INSTANCES_compact.png b/docs/2TARGETS_2INSTANCES_compact.png → docs/about/2TARGETS_2INSTANCES_compact.png
diff --git a/docs/DEPENDENCY.png → docs/about/DEPENDENCY.png b/docs/DEPENDENCY.png → docs/about/DEPENDENCY.png
diff --git a/docs/DEPENDENCY_compact.png → docs/about/DEPENDENCY_compact.png b/docs/DEPENDENCY_compact.png → docs/about/DEPENDENCY_compact.png
diff --git a/docs/about.rst → docs/about/about.rst b/docs/about.rst → docs/about/about.rst
@@ -25,10 +25,23 @@ Beetroot data model
 
 Since you, the reader, is most probably a seasoned programmer, I believe the most straightforward way of introducing you to the Beetroot is through data model.
 
-CMake (among other things) maintain internally an object for each defined target, and at the glance, the Beetroot's equivalent to the CMake target is a "`FEATUREBASE`" object class [1]. One target definition file can define multiple FeatureBase objects, because user can put several names in the `ENUM_TEMPLATES`. 
+CMake (among other things) maintain internally an object for each defined target, and at the glance, the Beetroot's equivalent to the CMake target is a "`FEATUREBASE`" object class [1]. `FEATUREBASE` also gets constructed if the user's code does not result in CMake targets (because e.g. it only modifies existing target). Also note that one target definition file (`targets.cmake`) can define multiple FeatureBase objects, because user can put several names in the `ENUM_TEMPLATES` stanza. 
 
 Each invocation of a function the requires a build of the target (e.g. `build_target()` or `get_existing_target()`) is internally represented by the object of the type "`INSTANCE`". In Beetroot INSTANCE and FEATUREBASE have one-to-many relationship; each INSTANCE is matched with a single FEATUREBASE, but a single FEATUREBASE may by linked to several INSTANCES.
 
+In plain CMake, this duality does not exist, the sequence of calls `add_library(foo ...)` and `target_link_libraries(myexec PRIVATE foo)` mean in simple English "build a library `foo`, and then make `myexec` depend on it". The `mytarget` alwyas gets defined or an error produced. On the other hand, in Beetroot one may express dependency relationship as "I need a library foo with a param `FLAG`". This would result in a new copy of library `foo` only if it has not been defined alsewhere with the sole param `FLAG`. It would be more equivalent to the 
+
+
+```
+if(NOT TARGET foo)
+	add_library(foo ...)
+endif()
+target_link_libraries(myexec PRIVATE foo)
+```
+
+except that such code can be dangerous, if we may not be sure with what options the `foo` was built. Beetroot takes care of that, by matching all the parameters `...` between the pre-existing `foo` and the `foo` definition.
+
+Beetroot also allows for more advanced dependency statement, expressed as "I need whatever library `foo` the project already comes with. Just make sure that among other parameters, it is compiled with a feature indicated by the param FLAG on". In that case Beetroot would gather all requested versions of the library `foo`, decide which are compatible with the specification, then decide if the feature `FLAG` can be added. If not - build a separate copy of `foo`.
 
 If user requires two targets but the only way they differ is through the link parameters, than it is not required to actually build two copies of them and in such case each `INSTANCE` link to the same `FEATUREBASE`:
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -16,8 +16,8 @@ The Beetroot Project's documentation
    :maxdepth: 2
    :caption: Contents:
 
-   about
-   start
+   about/about
+   start/start
    features
 
 

diff --git a/docs/start.rst b/docs/start.rst
@@ -129,6 +129,23 @@ We compile it as usual::
    $ ./hello_simple
    Hello World!
 
+
+Beetroot has built-in dependency graph generator in the dot language. This simples project can be visualized as 
+
+.. image:: 01_simplest_hello.png
+  :width: 700
+  :alt: Build tree of `build_target(HELLO_SIMPLE)`. Orange is `FEATUREBASE` with first title row showing target name and its internal ID. Blue is `INSTANCE` with title row showing its internal ID.
+
+There are minimum two types of object directly involved when building even the simplest of projects: `INSTANCE` and `FEATUREBASE`. If the user code actually produce a CMake target, then `FEATUREBASE` is a proxy class to it (with one-to-one relationship if user code define a new target), whereas `INSTANCE` also encapsulates the linking information - how should the dependency influence the callee. 
+
+Because it is very common case that there is one-to-one relationship between the `FEATUREBASE` and the `INSTANCE` - i.e. between the target and the place it is defined (as always the case in plaine CMake), the former diagram is simplified to this:
+
+.. image:: 01_simplest_hello_compact.png
+  :width: 700
+  :alt: Compacted build tree of `build_target(HELLO_SIMPLE)`. Orange is `FEATUREBASE` with first title row showing target name and its internal ID. Blue is `INSTANCE` with title row showing its internal ID.
+
+
+
 The Hello World with parameter (``02_parameter_hello``)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/start/01_simplest_hello.png b/docs/start/01_simplest_hello.png
diff --git a/docs/start/01_simplest_hello_compact.png b/docs/start/01_simplest_hello_compact.png
diff --git a/docs/start/02_parameter_hello.png b/docs/start/02_parameter_hello.png
diff --git a/docs/start/03_subprojects_basic.png b/docs/start/03_subprojects_basic.png
diff --git a/docs/start/04_subproject_pars.png b/docs/start/04_subproject_pars.png