diff --git a/CMakeLists.txt b/CMakeLists.txt index cbcf0ccc..0d6c10ef 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -182,3 +182,12 @@ if (BUILD_TESTING AND BUILDSYSTEM_TESTING) add_subdirectory(examples) endif() + +# Docs +set(IGNITION_CMAKE_DOXYGEN_DIR "${CMAKE_CURRENT_SOURCE_DIR}/doc/doxygen") +configure_file(${CMAKE_SOURCE_DIR}/api.md.in ${CMAKE_BINARY_DIR}/api.md) +configure_file(${CMAKE_SOURCE_DIR}/tutorials.md.in ${CMAKE_BINARY_DIR}/tutorials.md) +ign_create_docs( + API_MAINPAGE_MD "${CMAKE_BINARY_DIR}/api.md" + TUTORIALS_MAINPAGE_MD "${CMAKE_BINARY_DIR}/tutorials.md" + ) diff --git a/api.md.in b/api.md.in new file mode 100644 index 00000000..00f5d6c5 --- /dev/null +++ b/api.md.in @@ -0,0 +1,10 @@ +## Ignition @IGN_DESIGNATION_CAP@ + +Ignition @IGN_DESIGNATION_CAP@ is a component in Ignition, a set of libraries +designed to rapidly develop robot and simulation applications. + +## License + +The code associated with this documentation is licensed under an [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). + +This documentation is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/). diff --git a/tutorials.md.in b/tutorials.md.in new file mode 100644 index 00000000..7a404d4f --- /dev/null +++ b/tutorials.md.in @@ -0,0 +1,16 @@ +\page tutorials Tutorials + +Welcome to the Ignition @IGN_DESIGNATION_CAP@ tutorials. These tutorials +will guide you through the process of understanding the capabilities of the +Ignition @IGN_DESIGNATION_CAP@ library and how to use the library effectively. + + +**The tutorials** + +1. \subpage install "Installation" + +## License + +The code associated with this documentation is licensed under an [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0). + +This documentation is licensed under a [Creative Commons Attribution 4.0 International License](http://creativecommons.org/licenses/by/4.0/). diff --git a/tutorials/index.md b/tutorials/index.md new file mode 100644 index 00000000..c1fb58bd --- /dev/null +++ b/tutorials/index.md @@ -0,0 +1,6 @@ +# Introduction + +Ignition CMake is a component in the Ignition framework, a set +of libraries designed to rapidly develop robot applications. + +[http://ignitionrobotics.org](http://ignitionrobotics.org) diff --git a/tutorials/install.md b/tutorials/install.md new file mode 100644 index 00000000..6f4c6bd1 --- /dev/null +++ b/tutorials/install.md @@ -0,0 +1,130 @@ +\page install Installation + +# Install + +These instructions are for installing only Ignition CMake. If you're interested +in using all the Ignition libraries, not only Igniton CMake, check out this +[Ignition installation](https://ignitionrobotics.org/docs/latest/install). + +We recommend following the binary install instructions to get up and running as +quickly and painlessly as possible. + +The source install instructions should be used if you need the very latest +software improvements, if you need to modify the code, or if you plan to make a +contribution. + +## Binary Install + +### Ubuntu + +On Ubuntu, it's possible to install Ignition CMake as follows: + +Add OSRF packages: + + echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list + sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys D2486D2DD83DB69272AFE98867170598AF249743 + sudo apt update + +Install Ignition CMake: + + sudo apt install libignition-cmake<#>-dev + +Be sure to replace `<#>` with a number value, such as 1 or 2, depending on +which version you need. + +### macOS + +On macOS, add OSRF packages: + + ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" + brew tap osrf/simulation + +Install Ignition CMake: + + brew install ignition-cmake<#> + +Be sure to replace `<#>` with a number value, such as 1 or 2, depending on +which version you need. + +## Source Install + +### Prerequisites + +#### Ubuntu Bionic 18.04 or above + +Add OSRF packages: + + sudo apt update + sudo apt -y install wget lsb-release gnupg + sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list' + wget http://packages.osrfoundation.org/gazebo.key -O - | apt-key add - + sudo apt-add-repository -s "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -c -s) main" + +Clone source code: + + # This checks out the `main` branch. You can append `-b ign-cmake#` (replace # with a number) to checkout a specific version + git clone http://github.com/ignitionrobotics/ign-cmake + +Install dependencies + + sudo apt -y install $(sort -u $(find . -iname 'packages.apt') | tr '\n' ' ') + +Only on Bionic, update the GCC compiler version: + + sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-8 800 --slave /usr/bin/g++ g++ /usr/bin/g++-8 --slave /usr/bin/gcov gcov /usr/bin/gcov-8 + + +### Building from source + +Build and install as follows: + + cd ign-cmake + mkdir build + cd build + cmake .. + make -j4 + sudo make install + +# Documentation + +API documentation and tutorials can be accessed at +[https://ignitionrobotics.org/libs/cmake](https://ignitionrobotics.org/libs/cmake) + +You can also generate the documentation from a clone of this repository by following these steps. + +1. You will need [Doxygen](http://www.doxygen.org/). On Ubuntu Doxygen can be installed using + + sudo apt-get install doxygen + +2. Clone the repository + + git clone https://github.com/ignitionrobotics/ign-cmake + +3. Configure and build the documentation. + + cd ign-cmake + mkdir build + cd build + cmake .. + make doc + +4. View the documentation by running the following command from the `build` directory. + + firefox doxygen/html/index.html + +# Testing + +Follow these steps to run tests and static code analysis in your clone of this repository. + +1. Follow the [source install instruction](#source-install). + +2. Run tests. + + make test + +3. Static code checker. + + make codecheck + +See the [Writing Tests section of the contributor cmakede](https://ignitionrobotics.org/docs/all/contributing#writing-tests) for help creating or modifying tests. +