diff --git a/README.md b/README.md index 6774e12df..1c2e0f611 100644 --- a/README.md +++ b/README.md @@ -28,10 +28,6 @@ Ignition Transport, a component of [Ignition Robotics](https://ignitionrobotics. [Usage](#markdown-header-usage) -[Documentation](#markdown-header-documentation) - -[Testing](#markdown-header-testing) - [Folder Structure](#markdown-header-folder-structure) [Code of Conduct](#markdown-header-code-of-conduct) @@ -121,36 +117,6 @@ This issue is tracked [here](https://github.com/ignitionrobotics/ign-tools/issue Visit the [documentation page](https://ignitionrobotics.org/api/transport/8.0/index.html). -## Build documentation - -``` -cd build -make doc -``` - -Upload documentation to ignitionrobotics.org. - -``` -cd build -sh upload.sh -``` - -If you're creating a new release, then tell ignitionrobotics.org about - the new version. For example: - -``` -curl -k -X POST -d '{"libName":"transport", "version":"1.0.0", "releaseDate":"2017-10-09T12:10:13+02:00","password":"secret"}' https://api.ignitionrobotics.org/1.0/versions -``` - -# Testing - -Tests can be run by building the `test` target. From your build directory you -can run: - -``` -$ make test -``` - # Folder Structure ``` diff --git a/tutorials/02_installation.md b/tutorials/02_installation.md index c729e3ba7..ed50425ac 100644 --- a/tutorials/02_installation.md +++ b/tutorials/02_installation.md @@ -10,28 +10,30 @@ support platforms including major Linux distributions, Mac OS X and Windows. You can find all Ignition Transport versions at [https://ignitionrobotics.org/libs/transport](https://ignitionrobotics.org/libs/transport). -## Ubuntu Linux +# Binary Install + +## Ubuntu Setup your computer to accept software from *packages.osrfoundation.org*: - -```{.sh} +``` sudo sh -c 'echo "deb http://packages.osrfoundation.org/gazebo/ubuntu-stable `lsb_release -cs` main" > /etc/apt/sources.list.d/gazebo-stable.list' ``` Setup keys: - ``` wget http://packages.osrfoundation.org/gazebo.key -O - | sudo apt-key add - ``` Install Ignition Transport: - ``` sudo apt-get update sudo apt-get install libignition-transport8-dev ``` +Be sure to replace `<#>` with a number value, such as `1` or `2`, depending on +which version you need. + ## Mac OS X Ignition Transport and several of its dependencies can be compiled on OS @@ -45,13 +47,11 @@ use. Here are the instructions: Install homebrew, which should also prompt you to install the XCode command-line tools: - ``` ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" ``` Run the following commands: - ``` brew tap osrf/simulation brew install ignition-transport8 @@ -59,245 +59,215 @@ brew install ignition-transport8 ## Windows -At this moment, compilation has been tested on Windows 7 and 8.1 and is -supported when using [Visual Studio -2013](https://www.visualstudio.com/downloads/). Patches for other -versions are welcome. - -This installation procedure uses pre-compiled binaries in a local -workspace. To make things easier, use a MinGW shell for your editing -work (such as the [Git Bash Shell](https://msysgit.github.io/) with -[Git](https://gitforwindows.org/)), and -only use the Windows cmd for configuring and building. You might also -need to [disable the Windows -firewall](http://windows.microsoft.com/en-us/windows/turn-windows-firewall-on-off#turn-windows-firewall-on-off=windows-7). - -Make a directory to work in, e.g.: +Install [Conda package management system](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html). +Miniconda suffices. +Create if necessary, and activate a Conda environment: ``` -mkdir ign-ws -cd ign-ws +conda create -n ign-ws +conda activate ign-ws ``` -Download the following dependencies into that directory: - - * [cppzmq](http://packages.osrfoundation.org/win32/deps/cppzmq-noarch.zip) - * [Protobuf 2.6.0 (32-bit)](http://packages.osrfoundation.org/win32/deps/protobuf-2.6.0-win32-vc12.zip) - * [Protobuf 2.6.0 (64-bit)](http://packages.osrfoundation.org/win32/deps/protobuf-2.6.0-win64-vc12.zip) - -Choose one of these options: - - * [ZeroMQ 4.0.4 (32-bit)](http://packages.osrfoundation.org/win32/deps/zeromq-4.0.4-x86.zip) - * [ZeroMQ 4.0.4 (64-bit)](http://packages.osrfoundation.org/win32/deps/zeromq-4.0.4-amd64.zip) - -Unzip each of them. The Windows unzip utility will likely create an -incorrect directory structure, where a directory with the name of the -zip contains the directory that has the source files. Here is an -example: - +Install: ``` -ign-ws/cppzmq-noarch/cppzmq +conda install libignition-transport<#> --channel conda-forge ``` -The correct structure is +Be sure to replace `<#>` with a number value, such as 1 or 2, depending on +which version you need. -``` -ign-ws/cppzmq -``` +# Source Install -To fix this problem, manually move the nested directories up one level. +## Ubuntu Linux -Clone and prepare the Ignition Math dependency: +For compiling the latest version of Ignition Transport you will need an +Ubuntu distribution equal to 18.04 (Bionic) or newer. +Make sure you have removed the Ubuntu pre-compiled binaries before +installing from source: ``` -git clone https://github.com/ignitionrobotics/ign-math -cd ign-math -mkdir build +sudo apt-get remove libignition-transport8-dev ``` -In a Windows Command Prompt, load your compiler setup, e.g.: - +Install prerequisites. A clean Ubuntu system will need: ``` -"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" amd64 +sudo apt-get install git cmake pkg-config python ruby-ronn libprotoc-dev libprotobuf-dev protobuf-compiler uuid-dev libzmq3-dev libignition-msgs-dev ``` -In the Windows Command Prompt, configure and build: - +Clone the repository ``` -cd ign-math\build -..\configure -nmake install +git clone https://github.com/ignitionrobotics/ign-transport ``` -Clone and prepare the Ignition Msgs dependency: - +Configure and build ``` -git clone https://github.com/ignitionrobotics/ign-msgs -cd ign-msgs +cd ign-common mkdir build +cd build +cmake .. +make ``` -In the Windows Command Prompt, configure and build: +Configure Ignition Transport (choose either method a or b below): +A. Release mode (recommended): This will generate optimized code, but will not have + debug symbols. Use this mode if you don't need to use [GDB](https://www.gnu.org/software/gdb/) (advanced). ``` -cd ign-msgs\build -..\configure -nmake install +cmake .. ``` -Clone ign-transport: - +Note: You can use a custom install path to make it easier to switch +between source and debian installs: ``` -git clone https://github.com/ignitionrobotics/ign-transport -cd ign-transport +cmake -DCMAKE_INSTALL_PREFIX=/home/$USER/local .. ``` -In a Windows Command Prompt, load your compiler setup, e.g.: - +B. Debug mode: This will generate code with debug symbols. Ignition +Transport will run slower, but you'll be able to use GDB. ``` -"C:\Program Files (x86)\Microsoft Visual Studio 12.0\VC\vcvarsall.bat" amd64 +cmake -DCMAKE_BUILD_TYPE=Debug .. ``` -Configure and build: +The output from `cmake ../` may generate a number of errors and warnings +about missing packages. You must install the missing packages that have +errors and re-run `cmake ../`. Make sure all the build errors are +resolved before continuing (they should be there from the earlier step +in which you installed prerequisites). +Make note of your install path, which is output from cmake and should +look something like: ``` -mkdir build -cd build -..\configure -nmake -nmake install +-- Install path: /home/$USER/local ``` -You should now have an installation of ign-transport in -`ign-ws/ign-transport/build/install`. - -Before running any executables, you need to modify your `PATH` to -include the `bin` subdirectory of ZeroMQ to let Windows find dynamic -libs (similar to `LD_LIBRARY_PATH` on Linux). Don't put quotes around -the path, even if it contains spaces. E.g., if you're working in -`C:\My Stuff\ign-ws`: - +Build Ignition Transport: ``` -set PATH %PATH%;C:\My Stuff\ign-ws\ZeroMQ 4.0.4\bin +make -j4 ``` -Now build the examples: - -\code -cd ign-ws\ign-transport\example -mkdir build -cd build -..\configure -nmake -\endcode - -Now try an example. In one Windows terminal run: +Install Ignition Transport: +``` +sudo make install +``` +If you decide to install gazebo in a local directory you'll need to +modify your `LD_LIBRARY_PATH`: ``` -responser +echo "export LD_LIBRARY_PATH=/local/lib:$LD_LIBRARY_PATH" >> ~/.bashrc ``` -In another Windows terminal run: +### Uninstalling Source-based Install +If you need to uninstall Ignition Transport or switch back to a +debian-based install when you currently have installed the library from +source, navigate to your source code directory's build folders and run +`make uninstall`: ``` -requester +cd /tmp/ign-transport/build +sudo make uninstall ``` -### Install from sources (Ubuntu Linux) +## Windows -For compiling the latest version of Ignition Transport you will need an -Ubuntu distribution equal to 18.04 (Bionic) or newer. +### Prerequisites -Make sure you have removed the Ubuntu pre-compiled binaries before -installing from source: +First, follow the [ign-cmake](https://github.com/ignitionrobotics/ign-cmake) tutorial for installing Conda, Visual Studio, CMake, etc., prerequisites, and creating a Conda environment. +Navigate to `condabin` if necessary to use the `conda` command (i.e., if Conda is not in your `PATH` environment variable. You can find the location of `condabin` in Anaconda Prompt, `where conda`). + +Activate the Conda environment: ``` -sudo apt-get remove libignition-transport8-dev +conda activate ign-ws ``` -Install prerequisites. A clean Ubuntu system will need: - +Install prerequisites: ``` -sudo apt-get install git cmake pkg-config python ruby-ronn libprotoc-dev libprotobuf-dev protobuf-compiler uuid-dev libzmq3-dev libignition-msgs-dev +conda install zeromq cppzmq --channel conda-forge ``` -Clone the repository into a directory and go into it: +Install Ignition dependencies: +You can view available versions and their dependencies: ``` -git clone https://github.com/ignitionrobotics/ign-transport /tmp/ign-transport -cd /tmp/ign-transport +conda search libignition-transport* --channel conda-forge --info ``` -Create a build directory and go there: - +Install dependencies, replacing `<#>` with the desired versions: ``` -mkdir build -cd build +conda install libignition-cmake<#> libignition-msgs<#> libignition-tools<#> --channel conda-forge ``` -Configure Ignition Transport (choose either method a or b below): +#### Building from Source -A. Release mode (recommended): This will generate optimized code, but will not have - debug symbols. Use this mode if you don't need to use [GDB](https://www.gnu.org/software/gdb/) (advanced). +1. Navigate to where you would like to build the library, and clone the repository. + ``` + # Optionally, append `-b ign-transport#` (replace # with a number) to check out a specific version + git clone https://github.com/ignitionrobotics/ign-transport.git + ``` -``` -cmake ../ -``` +2. Configure and build + ``` + cd ign-transport + mkdir build + cd build + cmake .. -DBUILD_TESTING=OFF # Optionally, -DCMAKE_INSTALL_PREFIX=path\to\install + cmake --build . --config Release + ``` -Note: You can use a custom install path to make it easier to switch -between source and debian installs: +3. Optionally, install. You will likely need to run a terminal with admin privileges for this call to succeed. + ``` + cmake --install . --config Release + ``` -``` -cmake -DCMAKE_INSTALL_PREFIX=/home/$USER/local ../ -``` +4. Optionally, build the examples -B. Debug mode: This will generate code with debug symbols. Ignition -Transport will run slower, but you'll be able to use GDB. + If you installed to a custom location, you may need to specify ``-DCMAKE_PREFIX_PATH``, pointing to the directory containing the file ``ignition-transport9-config.cmake``. + That file is installed to the ``CMAKE_INSTALL_PREFIX``, for example, ``path\to\install\ignition-transport<#>\lib\cmake\ignition-transport<#>``. + ``` + cd ign-transport\example + mkdir build + cd build + cmake .. # Optionally, -DCMAKE_PREFIX_PATH=path\to\cmake\config + cmake --build . --config Release + ``` -``` -cmake -DCMAKE_BUILD_TYPE=Debug ../ -``` + Try an example + ``` + responser + ``` -The output from `cmake ../` may generate a number of errors and warnings -about missing packages. You must install the missing packages that have -errors and re-run `cmake ../`. Make sure all the build errors are -resolved before continuing (they should be there from the earlier step -in which you installed prerequisites). + In another terminal, run + ``` + requester + ``` -Make note of your install path, which is output from cmake and should -look something like: +# Documentation +Visit the [documentation page](https://ignitionrobotics.org/api/transport/8.0/index.html). + +## Build documentation ``` --- Install path: /home/$USER/local +cd build +make doc ``` -Build Ignition Transport: - +Upload documentation to ignitionrobotics.org. ``` -make -j4 +cd build +sh upload.sh ``` -Install Ignition Transport: - +If you're creating a new release, then tell ignitionrobotics.org about + the new version. For example: ``` -sudo make install +curl -k -X POST -d '{"libName":"transport", "version":"1.0.0", "releaseDate":"2017-10-09T12:10:13+02:00","password":"secret"}' http s://api.ignitionrobotics.org/1.0/versions ``` -If you decide to install gazebo in a local directory you'll need to -modify your `LD_LIBRARY_PATH`: +# Testing +Tests can be run by building the `test` target. From your build directory you +can run: ``` -echo "export LD_LIBRARY_PATH=/local/lib:$LD_LIBRARY_PATH" >> ~/.bashrc +make test ``` -### Uninstalling Source-based Install - -If you need to uninstall Ignition Transport or switch back to a -debian-based install when you currently have installed the library from -source, navigate to your source code directory's build folders and run -`make uninstall`: - -\code -cd /tmp/ign-transport/build -sudo make uninstall -\endcode