Document qibuild unique design goals and features

doc/source/beginner/overview.rst

@@ -69,14 +69,73 @@ qibuild is composed of two parts:
  taking dependencies into account and generate re-distributable binary
  packages.
 
+What makes qiBuild different ?
+++++++++++++++++++++++++++++++
 
-Is qibuild the only one build framework?
-++++++++++++++++++++++++++++++++++++++++
+The good parts
+~~~~~~~~~~~~~~
 
+* Full support for Visual Studio
 
-Of course not!
+* Full support for cross-compilation (hosts: linux, mac: targets : x86, arm, android, ...)
 
-You can have a loot at
+* Comes with a tool to use pre-compiled dependencies
+
+* No environment variables required, and keep your environment clean
+
+* Written in Python like many others but:
+
+ * Python2/Python3 compatible
+
+ * >80% test coverage
+
+ * Only pure-Python dependencies, for easier installation on Windows
+
+* Can find dependencies **from the sources**. For instance, in a worktree with
+ two different CMake projects , ``world`` and ``hello``, when compiling ``hello``,
+ we will find ``world`` headers directly from ``world`` sources.
+
+* Automatic install rules (you have to *explicitly* exclude targets from installation)
+
+* ``qibuild package --standalone`` generates an archive that is:
+
+ * relocatable
+
+ * and work across linux distributions
+
+* Full Python support : you can write Python code that use extensions written in C++
+ with ease, and run the C++ and the Python tests with the same tool
+
+* Each project build dir contains a nice ``sdk`` folder with files where you expect them
+ (``.dlls`` and ``.exe`` in ``sdk/bin``, ``.so`` in ``sdk/lib/`` and data in
+ ``sdk/share``)
+
+* You can deploy your code to a remote host via ``ssh`` and ``rsync``
+
+* You can also deploy or install your tests, and then only run them with
+ ``qitest``
+
+The bad parts
+~~~~~~~~~~~~~
+
+* Requires a :term:`worktree`. So it's useless if you have only one project.
+
+* Re-implements
+ `CMake build system
+ <https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>`_
+
+* Cannot directly use upstream ``Find*.cmake``` files, especially if they
+ contained exported target (We have hacks for Qt5 because of this)
+
+* Generated ``-config.cmake`` files could be used by other CMake code, but they
+ contain a ``_DEPENDS`` variable that only ``qiBuild`` can understand.
+ Also, they use old-style ``*_INCLUDE_DIRS``, ``*_LIBRARIES`` variables instead
+ of modern exported targets
+
+qibuild compared to other build frameworks
++++++++++++++++++++++++++++++++++++++++++++
+
+Have a look at
 
 .. toctree::
  :maxdepth: 1

doc/source/beginner/qibuild/other/cmake.rst

@@ -77,6 +77,31 @@ the library)
 Also note how easy it is to make sure that someone using bar will only depend on ``FOO_SPAM``,
 and not the whole ``FOO`` package.
 
+Note: ``CMake`` has evolved a lot since this section was written.
+
+Here's how the code looks like with modern CMake:
+(As explained in
+`CMake build system documentation
+<https://cmake.org/cmake/help/latest/manual/cmake-buildsystem.7.html>`_)
+
+.. code-block:: cmake
+
+ include(GNUInstallDirs)
+
+ find_package(foo COMPONENTS spam eggs)
+
+ add_library(bar bar.h bar.c)
+ target_include_directories(bar Foo::Spam)
+ target_link_libraries(bar Foo::Spam)
+
+ add_library(baz baz.h baz.c)
+
+ target_link_libraries(baz baz)
+
+ install(TARGETS baz EXPORT baz
+ LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})
+
+
 
 CMake variables
 ---------------