From 142528f20de5d965d4aef7570cd5633c28101c6e Mon Sep 17 00:00:00 2001 From: Thomas Braun Date: Wed, 6 Feb 2019 10:47:11 +0100 Subject: [PATCH] Rework documentation regarding installation --- INSTALL.md | 89 ++++++++++++++++++++++++++++++++++++++++-------------- README.md | 71 +++---------------------------------------- 2 files changed, 70 insertions(+), 90 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 8d57a48de..72f7e92fa 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,21 +1,32 @@ -[DRAFT] - # Prerequisites * [tango-idl](https://github.com/tango-controls/tango-idl) +* Other required packages can be installed on apt-based linux systems via + * add deb-src entries for main and contrib (debian) or main, restricted and universe (ubuntu) into /etc/apt/sources.list + * `sudo apt-get update` + * `sudo apt-get build-dep libtango9` * docker and docker-engine (for tests) -# How to build and install using cmake +# How to build and install + +- `git clone https://github.com/tango-controls/cppTango` +- `cd cppTango` +- `mkdir build` +- `cd build` +- `cmake ..` +- `make [-j NUMBER_OF_CPUS]` +- `sudo make install` -- clone -- cd into cloned repo -- mkdir build -- cd build -- cmake .. -- make [-j NUMBER_OF_CPUS] -- sudo make install +## Available are the following cmake options: -cmake options are: `[-DCMAKE_INSTALL_PREFIX=] [-DOMNI_BASE=] [-DCPPZMQ_BASE=] [-DZMQ_BASE=] [-DIDL_BASE=] [-DCMAKE_BUILD_TYPE=Release|Debug] [-DCMAKE_VERBOSE_MAKEFILE=true]` +- `-DCMAKE_INSTALL_PREFIX=` +- `-DIDL_BASE=` +- `-DOMNI_BASE=` +- `-DCPPZMQ_BASE=` +- `-DZMQ_BASE=` +- `-DCMAKE_BUILD_TYPE=` +- `-DCMAKE_VERBOSE_MAKEFILE=true` +- `-DTANGO_USE_USING_NAMESPACE=` choose `OFF` for modern builds Typical output: @@ -54,17 +65,49 @@ When compiling on Ubuntu 16.04 or on Debian stretch, the following error can occ poll_list[old_poll_nb].socket = *tmp_sock; ``` -This is due to incompatibility of zmq.hpp file provided in libzmq3-dev:4.1.7 (ubuntu 16.04), i.e. it is not possible to compile cppTango using zmq.hpp file provided by libzmq3-dev:4.1.7 (ubuntu 16.04). +This is due to incompatibility of zmq.hpp file provided in libzmq3-dev:4.1.7 +(ubuntu 16.04), i.e. it is not possible to compile cppTango using zmq.hpp file +provided by libzmq3-dev:4.1.7 (ubuntu 16.04). + +This requires installing [cppzmq](https://github.com/zeromq/cppzmq) via: + +``` +git clone https://github.com/zeromq/cppzmq +cd cppzmq +mkdir build +cd build +cmake -DENABLE_DRAFTS=OFF -DCPPZMQ_BUILD_TESTS=OFF .. +sudo make install +``` + +# Using pkg-config -The following workaround can be applied: +Once installed cppTango provides [pkg-config](https://en.wikipedia.org/wiki/Pkg-config) file `tango.pc` -Download and install [cppzmq](https://github.com/zeromq/cppzmq) (version 4.2.2 for instance). Install it in some folder. +One can use it to resolve libtango dependencies in his project, for instance using cmake: -Build cppTango using installed cppzmq, using the following cmake command during the build process: +```cmake +include(FindPkgConfig) +pkg_search_module(TANGO_PKG REQUIRED tango) -`cmake .. -DCPPZMQ_BASE=` +#... -This problem is addressed in issue #273 and Pull Request #421. +link_directories(${TANGO_PKG_LIBRARY_DIRS}) + +#note TANGO_PKG_XXX usage +add_executable(${PROJECT_NAME} ${SOURCES} ${HEADERS}) +target_include_directories(${PROJECT_NAME} PUBLIC ${CMAKE_CURRENT_SOURCE_DIR} ${TANGO_PKG_INCLUDE_DIRS}) +target_compile_options(${PROJECT_NAME} PUBLIC -std=c++11) +target_compile_definitions(${PROJECT_NAME} PUBLIC ${TANGO_PKG_CFLAGS_OTHER}) +target_link_libraries(${PROJECT_NAME} PUBLIC ${TANGO_PKG_LIBRARIES}) +``` + +`tango.pc` provides default installation directory for all Tango devices linked against this libtango: + +```bash +pkg-config --variable=tangodsdir tango +/usr/bin +``` # How to setup tests @@ -117,14 +160,14 @@ Checking test dependency graph... Checking test dependency graph end test 1 Start 1: log4tango_test - + - + 100% tests passed, 0 tests failed out of 59 Total Test time (real) = 843.30 sec -Run command: /home/tango/src/build/cpp_test_suite/environment/post_test.sh +Run command: /home/tango/src/build/cpp_test_suite/environment/post_test.sh ``` The whole test suite takes ~ 15 min @@ -171,9 +214,9 @@ test 12 12: Test command: /storage/Projects/org.tango/git/cppTango/build/cpp_test_suite/old_tests/attr_misc "test/debian8/10" 12: Test timeout computed to be: 1500 -12: +12: 12: new DeviceProxy(test/debian8/10) returned -12: +12: 12: Setting/Getting attribute info --> OK 12: Writing outside attribute limits --> OK 12: Min alarm detection (on a float spectrum) --> OK @@ -203,4 +246,4 @@ See [CTest guide](https://cmake.org/Wiki/CMake/Testing_With_CTest) ``` $ make stop-tango -``` \ No newline at end of file +``` diff --git a/README.md b/README.md index 17af045e5..2ca780877 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ TANGO is an object-oriented distributed control system. In TANGO all objects are representations of devices, which can be on the same computer or distributed over a network. Communication between devices can be synchronous, asynchronous or event driven. -The object model in TANGO supports methods, attributes and properties. TANGO provides an API which hides all the details of network access and provides object browsing, discovery, and security features. +The object model in TANGO supports methods, attributes and properties. TANGO provides an API which hides all the details of network access and provides object browsing, discovery, and security features. For more information please visit [www.tango-controls.org](http://www.tango-controls.org). @@ -50,72 +50,9 @@ API reference: [tango-controls.github.io/cppTango-docs](https://tango-controls.g Old Manuals: [tango-controls.org/documentation/kernel](http://www.tango-controls.org/documentation/kernel/) -# How to build and install using cmake +# How to build and install -`mkdir build; cd build; cmake .. [-DCMAKE_INSTALL_PREFIX=] [-DIDL_BASE=] [-DOMNI_BASE=] [-DCPPZMQ_BASE=] [-DCMAKE_BUILD_TYPE=Release|Debug] [-DCMAKE_VERBOSE_MAKEFILE=true]; make; make install` - -More information is in [INSTALL file](https://github.com/tango-controls/cppTango/blob/tango-9-lts/INSTALL.md) - -# Using pkg-config - -Once installed cppTango provides [pkg-config](https://en.wikipedia.org/wiki/Pkg-config) file `tango.pc` - -One can use it to resolve libtango dependencies in his project, for instance using cmake: - -```cmake -include(FindPkgConfig) -pkg_search_module(TANGO_PKG REQUIRED tango) - -#... - -link_directories(${TANGO_PKG_LIBRARY_DIRS}) - -#note TANGO_PKG_XXX usage -add_executable(${PROJECT_NAME} ${SOURCES} ${HEADERS}) -target_include_directories(${PROJECT_NAME} PUBLIC ${CMAKE_CURRENT_SOURCE_DIR} ${TANGO_PKG_INCLUDE_DIRS}) -target_compile_options(${PROJECT_NAME} PUBLIC -std=c++11) -target_compile_definitions(${PROJECT_NAME} PUBLIC ${TANGO_PKG_CFLAGS_OTHER}) -target_link_libraries(${PROJECT_NAME} PUBLIC ${TANGO_PKG_LIBRARIES}) -``` - -`tango.pc` provides default installation directory for all Tango devices linked against this libtango: - -```bash -pkg-config --variable=tangodsdir tango -/usr/bin -``` - -# How to test - -### 1. First build everything - - `mkdir build; cd build; cmake ..; make` - -### 2. Start TANGO environment - - `make start-tango` - - Typical output: -Note env.TANGO_HOST value: this is normal TANGO_HOST that can be used, for instance, in Jive - -``` -Setup test environment - 174fda8cad89ac457a6129c599368d2842547575eac05f1d9b4ad60966cf0018 - CONTAINER=6130013cf55d420552df9dddd488b7564d58f49d10831d4880774443faf1a22b - TANGO_HOST=172.17.0.3:10000 - Create tango_host file - Wait till tango-cs is online -``` - -### 3. Run tests - `make run-tests` - - Before running tests CTest runs conf_devtest (located in cpp_test_suite/new_tests) and starts DevTest and FwdTest device servers (located in cpp_test_ds) - -### 4. Shutdown TANGO environment - `make stop-tango` - -For information on how to run individual tests see [INSTALL file](https://github.com/tango-controls/cppTango/blob/master/INSTALL.md) +See [INSTALL file](INSTALL.md). # How to contribute @@ -130,7 +67,7 @@ See [corresponding wiki page](https://github.com/tango-controls/cppTango/wiki/Co 4. Code review: most projects (all except single-developer ones) should only allow commits to the master branch after peer review. This can be enforced by the convention that all commits to master must be done via a Pull request and the pull request approved by a person different from the author of the commit. 5. Releases (named versions): * Simple projects may be ok with just tagging certain (ideally, all) commits done to the master branch with a version number. With this system, only one release is actively maintained simultaneously. - + * More complex projects may require to simultaneously maintain more than one release (e.g. Tango may choose to support bugfixes in Tango9 even after Tango10 is released). In this case, releases may be done on release branches starting from master (see APPENDIX I for an example) 6. Semantic versioning is recommended. 7. Public automatic testing/continuous integration (e.g., via Travis) is recommended