Merge pull request #290 from dawagner/improve-build-experience

Improve build experience

Add some doc, make it easy to list available configuration options and clean appveyor.yml up a bit.

Author: dawagner

CMakeLists.txt

@@ -36,11 +36,16 @@ endif(COMMAND cmake_policy)
 
 project(parameter-framework)
 
+include(CMakeDependentOption)
+
 option(COVERAGE "Build with coverage support" OFF)
-option(BASH_COMPLETION "Install bash completion configuration" ON)
+cmake_dependent_option(BASH_COMPLETION "Install bash completion configuration"
+    ON
+    UNIX # Only allow installing bash completion on Unix environments
+    OFF)
 option(DOXYGEN "Enable doxygen generation (you still have to run 'make doc')" OFF)
 option(REQUIREMENTS "Generate the html version of the 'requirements' documentation" OFF)
-option(PYTHON_BINDINGS "Python library to use the Parameter Framrwork from python" ON)
+option(PYTHON_BINDINGS "Python library to use the Parameter Framework from python" ON)
 option(C_BINDINGS "Library to use the Parameter Framework using a C API" ON)
 
 

README.md

@@ -64,11 +64,48 @@ See [the wiki on github](https://github.com/01org/parameter-framework/wiki).
 
 ## Compiling
 
+### Dependencies
+
+In order to compile you'll need, at the very least:
+
+- CMake (v2.8.12 or later);
+- A C/C++ compiler supporting C++11;
+- libxml2 headers and libraries (Provided by the `libxml2-dev` on debian-based
+distributions);
+- Standalone ASIO (1.10.6 or later) (Provided by `libasio-dev` on debian-based
+distributions) ASIO is C++ header-only ASynchronous-IO library.
+
+If you want to compile the *Python bindings*, you'll also need:
+
+- SWIG 2.0 (A binding generator);
+- Python2.7 development environment (Provided by `python2.7-dev` on debian-based
+distributions)
+
+If you want to *compile and run the tests*, you'll also need:
+
+- Catch (Provided by `catch` on debian-based distributions). Catch is a
+single-header test framework - as such you may also download it directly
+[here](https://raw.githubusercontent.com/philsquared/Catch/master/single_include/catch.hpp);
+- Python2.7 (Provided by `python2.7` on debian-based distribution - it is
+preinstalled on most distributions).
+
+If you want to *build the code documentation*, you'll need `doxygen` and
+`graphviz`. This doc is already available to you - see the wiki.
+
+**To list all available configuration options, try** `cmake -L` (you may also
+filter-out lines starting with `CMAKE_`).
+
+### How-To
+
+If you are already familiar with CMake, you know what to do.
+
 Run `cmake .` then `make`.  You may then install libraries, headers and
 binaries with `make install`.  By default, they are installed under
 `/usr/local` on unix OSes; if you want to install them under a custom
 directory, you may do so by passing it to the `cmake .` command; e.g.
 
+    # Always use absolute paths in CMake "-D" options: you don't know where
+    # relative paths will be evaluated from.
     cmake -DCMAKE_INSTALL_PREFIX=/path/to/custom/install .
 
 If you want to provide your own dependencies (e.g. your own version of
@@ -92,3 +129,20 @@ After a build you may want to run the parameter-framework tests with
 
 You may take a look at `.travis.yml` and `appveyor.yml` for examples on how we
 build the Parameter Framework in the CI.
+
+### Compiling on Windows
+
+If you don't already have libxml2 headers/libraries and don't want to build them
+by yourself, we have a precompiled version for x86-64.
+
+Compiled with Visual Studio 12 2013:
+- [in debug configuration](https://01.org/sites/default/files/libxml2-x86_64-debug-3eaedba1b64180668fdab7ad2eba549586017bf3.zip)
+- [in release configuration](https://01.org/sites/default/files/libxml2-x86_64-3eaedba1b64180668fdab7ad2eba549586017bf3.zip)
+
+We have mirrored ASIO 1.10.6 [here](https://01.org/sites/default/files/asio-1.10.6.tar.gz).
+
+Once you have downloaded and uncompressed these two dependencies, add the
+following two entries to `CMAKE_PREFIX_PATH`:
+
+    /path/to/libxml2-x86_64/
+    /path/to/asio-1.10.6/

appveyor.yml

@@ -43,6 +43,8 @@ install:
       7z x -i"!asio*/include" asio-1.10.6.tar)
   - if not exist catch (
       wget --no-check-certificate https://raw.github.com/philsquared/Catch/master/single_include/catch.hpp --directory-prefix catch )
+  - set DEBUG_LIBXML2_PATH=%APPVEYOR_BUILD_FOLDER%\libxml2-x86_64-debug
+  - set RELEASE_LIBXML2_PATH=%APPVEYOR_BUILD_FOLDER%\libxml2-x86_64
 
   # Setup Visual studio build environement
   - '"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" x86_amd64'
@@ -59,33 +61,33 @@ build_script:
   - mkdir build && cd build
 
   - mkdir 64bits-debug && cd 64bits-debug
-  # Add debug libxml2.dll in the path so that cmake & tests can find it
-  - set OLD_PATH=%PATH% && set PATH=%APPVEYOR_BUILD_FOLDER%\libxml2-x86_64-debug\bin;%PATH%
-  - cmake -G "NMake Makefiles" -DPYTHON_BINDINGS=OFF -DBASH_COMPLETION=OFF -DCMAKE_PREFIX_PATH="%PREFIX_PATH%" ..\..
+  # Add debug libxml2.dll in the path so that tests can find it
+  - set TEST_PATH=%DEBUG_LIBXML2_PATH%\bin
+  - cmake -G "NMake Makefiles" -DPYTHON_BINDINGS=OFF -DCMAKE_PREFIX_PATH="%PREFIX_PATH%;%DEBUG_LIBXML2_PATH%" ..\..
   - cmake --build . --config debug
   - ctest --build-config debug %CTEST_PARAMS%
-  - set PATH=%OLD_PATH% && cd ..
+  - cd ..
 
   - mkdir 64bits-release & cd 64bits-release
-  # Add release libxml2.dll in the path so that cmake & tests can find it
-  - set OLD_PATH=%PATH% && set PATH=%APPVEYOR_BUILD_FOLDER%\libxml2-x86_64\bin;%PATH%
-  - cmake -G "Visual Studio 12 2013 Win64" -DCMAKE_BUILD_TYPE=Release -DPYTHON_BINDINGS=OFF -DBASH_COMPLETION=OFF -DCMAKE_PREFIX_PATH="%PREFIX_PATH%" -DCMAKE_INSTALL_PREFIX=%INSTALL% ..\..
+  # Add debug libxml2.dll in the path so that tests can find it
+  - set TEST_PATH=%RELEASE_LIBXML2_PATH%\bin
+  - cmake -G "Visual Studio 12 2013 Win64" -DPYTHON_BINDINGS=OFF -DCMAKE_PREFIX_PATH="%PREFIX_PATH%;%RELEASE_LIBXML2_PATH%" -DCMAKE_INSTALL_PREFIX=%INSTALL% ..\..
   # Build, test and install
   - cmake --build . --config release
   - ctest --build-config release %CTEST_PARAMS%
   - cmake --build . --config release --target install
-  - set PATH=%OLD_PATH% && cd ..
+  - cd ..
 
   # build and test the skeleton plugin against the previously-installed build; this serves as a smoke test of the whole stack
   - mkdir skeleton && cd skeleton
   # %INSTALL%\lib is where the skeleton plugin is installed (see comment below)
   # %INSTALL%\bin is where parameter.dll is installed
-  - set OLD_PATH=%PATH% && set PATH=%APPVEYOR_BUILD_FOLDER%\libxml2-x86_64\bin;%INSTALL%\lib;%INSTALL%\bin;%PATH%
-  - cmake -G "Visual Studio 12 2013 Win64" -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=%INSTALL% -DCMAKE_PREFIX_PATH=%INSTALL% %APPVEYOR_BUILD_FOLDER%\skeleton-subsystem
+  # Also add the path where the release libxml2.dll has been extracted
+  - set TEST_PATH=%RELEASE_LIBXML2_PATH%\bin;%INSTALL%\lib;%INSTALL%\bin
+  - cmake -G "Visual Studio 12 2013 Win64" -DCMAKE_INSTALL_PREFIX=%INSTALL% -DCMAKE_PREFIX_PATH=%INSTALL% %APPVEYOR_BUILD_FOLDER%\skeleton-subsystem
   # Unfortunately, the skeleton test currently doesn't work on
   # multi-configuration build systems (Visual Studio is one of those) without
   # installing the plugin
   - cmake --build . --config release --target install
   - ctest --build-config release %CTEST_PARAMS%
-  - set PATH=%OLD_PATH% && cd ..
   - cd ..

bindings/python/CMakeLists.txt

@@ -26,7 +26,20 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-find_package(SWIG REQUIRED)
+find_package(SWIG)
+# Hide these variables from CMake GUIs and `cmake -L`
+set_property(CACHE
+    SWIG_DIR SWIG_EXECUTABLE SWIG_VERSION
+    PROPERTY ADVANCED TRUE)
+if (NOT SWIG_FOUND)
+    message(FATAL_ERROR
+        "Swig is needed to compile the Python bindings but was not found."
+        "Please either install swig2.0 or disable Python bindings by setting"
+        "PYTHON_BINDINGS to OFF (e.g. '-DPYTHON_BINDINGS=OFF' in the"
+        "invocation of CMake.). See the 'Compilation' section of README.md"
+        "for more details.")
+endif()
+
 include(${SWIG_USE_FILE})
 
 # Force usage of Python 2.7.x ...

ctest/CMakeLists.txt

@@ -60,7 +60,7 @@ function(set_test_env TestName)
     #
     # Thus all `;` in environment variables must be escaped
     # before inserting them in the ENVIRONMENT PROPERTY.
-    string(REPLACE ";" "\\;" TEST_PATH "$ENV{PATH}")
+    string(REPLACE ";" "\\;" TEST_PATH "$ENV{PATH};$ENV{TEST_PATH}")
     string(REPLACE ";" "\\;" TEST_LD_LIBRARY_PATH "$ENV{LD_LIBRARY_PATH}")
     string(REPLACE ";" "\\;" TEST_PYTHONPATH "$ENV{PYTHONPATH}")
 

doc/CMakeLists.txt

@@ -26,7 +26,6 @@
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-include(CMakeDependentOption)
 # Only present DOXYGEN_GRAPHS if DOXYGEN is ON and if so, default to ON.
 # Else, set to OFF.
 cmake_dependent_option(DOXYGEN_GRAPHS

remote-processor/CMakeLists.txt

@@ -44,6 +44,8 @@ find_package(Threads REQUIRED)
 # If asio isn't installed in a standard directory, add the correct directory to
 # CMAKE_PREFIX_PATH (see the main README for more information).
 find_path(ASIO_DIR NAMES asio.hpp)
+# Hide this variable from CMake GUIs and `cmake -L`
+set_property(CACHE ASIO_DIR PROPERTY ADVANCED TRUE)
 # FIXME: asio header should not leak to remote-processor users
 target_include_directories(remote-processor SYSTEM PUBLIC "${ASIO_DIR}")
 

test/catch/CMakeLists.txt

@@ -31,6 +31,7 @@ if(BUILD_TESTING)
     #      Unfortunately gtest is very hard to setup as not binary distributed
     #      catch is only one header so it is very easy
     find_path(CATCH_HEADER catch.hpp)
+    set_property(CACHE CATCH_HEADER PROPERTY ADVANCED TRUE)
     if (NOT CATCH_HEADER)
         message(SEND_ERROR
 " Catch header `catch.hpp' could not be found.
@@ -40,7 +41,6 @@ if(BUILD_TESTING)
       https://raw.github.com/philsquared/Catch/master/single_include/catch.hpp
     Then either:
       - append the download folder to the `CMAKE_INCLUDE_PATH' or `CMAKE_PREFIX_PATH' variable
-      - set cmake variable `CATCH_HEADER' to the header directory
       - copy it in a standard location (/usr/include on most linux distribution).
   To remove test dependancies all together, set `BUILD_TESTING' to false.
     It will disable test targets, thus the framework they depend on.")

test/test-fixed-point-parameter/CMakeLists.txt

@@ -27,11 +27,11 @@
 # SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 if (BUILD_TESTING AND PYTHON_BINDINGS)
-    find_program(python2 python2)
+    find_package(PythonInterp 2.7 REQUIRED)
 
     add_test(NAME fix_point_parameter
              WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
-             COMMAND ${python2} Main.py)
+             COMMAND ${PYTHON_EXECUTABLE} Main.py)
 
     # Custom function defined in the top-level CMakeLists
     set_test_env(fix_point_parameter)