From 284bf79329c49a30d4f6232a241c18ffc43b6369 Mon Sep 17 00:00:00 2001 From: Dimitri Merejkowsky Date: Thu, 7 Apr 2016 17:24:07 +0200 Subject: [PATCH] document qibuild's unique design goals and features Change-Id: I906f81e353e84eff90f42bbf92ed6b760fd261a5 --- doc/source/beginner/overview.rst | 67 +++++++++++++++++++-- doc/source/beginner/qibuild/other/cmake.rst | 25 ++++++++ 2 files changed, 88 insertions(+), 4 deletions(-) diff --git a/doc/source/beginner/overview.rst b/doc/source/beginner/overview.rst index e45e3e421..b11d1305d 100644 --- a/doc/source/beginner/overview.rst +++ b/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 + `_ + +* 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 diff --git a/doc/source/beginner/qibuild/other/cmake.rst b/doc/source/beginner/qibuild/other/cmake.rst index 4b3a9e92e..cef079faf 100644 --- a/doc/source/beginner/qibuild/other/cmake.rst +++ b/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 +`_) + +.. 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 ---------------