From 9d081055fbd97171d479f510f2e1dd8a31858dea Mon Sep 17 00:00:00 2001 From: Chris Lalancette Date: Fri, 6 Dec 2024 10:48:22 -0500 Subject: [PATCH] Cleanup the Windows instructions for using conda/pixi. Note that this does not currently include instructions for debug, since we don't know how we are going to solve that yet. Signed-off-by: Chris Lalancette --- .../Windows-Development-Setup.rst | 169 +++++++----------- .../Installation/Windows-Install-Binary.rst | 92 ++++++---- .../_Windows-Install-Prerequisites.rst | 166 ----------------- 3 files changed, 119 insertions(+), 308 deletions(-) delete mode 100644 source/Installation/_Windows-Install-Prerequisites.rst diff --git a/source/Installation/Alternatives/Windows-Development-Setup.rst b/source/Installation/Alternatives/Windows-Development-Setup.rst index 2670766a14f..b227f2a7340 100644 --- a/source/Installation/Alternatives/Windows-Development-Setup.rst +++ b/source/Installation/Alternatives/Windows-Development-Setup.rst @@ -9,7 +9,7 @@ Windows (source) :depth: 2 :local: -This guide is about how to setup a development environment for ROS 2 on Windows. +This page explains how to setup a development environment for ROS 2 on Windows. System requirements ------------------- @@ -22,36 +22,84 @@ Language support Make sure you have a locale which supports ``UTF-8``. For example, for a Chinese-language Windows 10 installation, you may need to install an `English language pack `_. -.. include:: ../_Windows-Install-Prerequisites.rst +Create a location for the ROS 2 installation +-------------------------------------------- -Install additional prerequisites from Chocolatey -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +This location will contain both the installed binary packages, plus the ROS 2 installation itself. -.. code-block:: bash +Start a powershell session (usually by clicking on the start menu, then typing ``powershell``). - choco install -y cppcheck curl git winflexbison3 +Then create a directory to store the installation. +Because of Windows path-length limitations, this should be as short as possible. +We'll use ``C:\dev`` for the rest of these instructions. -You will need to append the Git cmd folder ``C:\Program Files\Git\cmd`` to the PATH (you can do this by clicking the Windows icon, typing "Environment Variables", then clicking on "Edit the system environment variables". -In the resulting dialog, click "Environment Variables", the click "Path" on the bottom pane, then click "Edit" and add the path). +.. code-block:: console -Install Python prerequisites -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + md C:\dev -Install additional Python dependencies: +Install prerequisites +--------------------- -.. code-block:: bash +ROS 2 uses `conda-forge `__ as a backend for packages, with `pixi `__ as the frontend. + +Install MSVC +^^^^^^^^^^^^ + +In order to compile the ROS 2 code, the MSVC compiler must be installed. +Currently it is recommended to use MSVC 2019. + +Continue using the previous powershell session, and run the following command to download it: + +.. code-block:: console + + irm https://aka.ms/vs/16/release/vs_buildtools.exe -OutFile vs_buildtools_2019.exe + +Now install MSVC 2019 (this will take some time): + +.. code-block:: console + + vs_buildtools_2019.exe --quiet --wait --norestart --add Microsoft.Component.MSBuild --add Microsoft.Net.Component.4.6.1.TargetingPack --add Microsoft.Net.Component.4.8.SDK --add Microsoft.VisualStudio.Component.CoreBuildTools --add Microsoft.VisualStudio.Component.Roslyn.Compiler --add Microsoft.VisualStudio.Component.TextTemplating --add Microsoft.VisualStudio.Component.VC.CLI.Support --add Microsoft.VisualStudio.Component.VC.CoreBuildTools --add Microsoft.VisualStudio.Component.VC.CoreIde --add Microsoft.VisualStudio.Component.VC.Redist.14.Latest --add Microsoft.VisualStudio.Component.VC.Tools.x86.x64 --add Microsoft.VisualStudio.Component.Windows10SDK --add Microsoft.VisualStudio.Component.Windows10SDK.19041 --add Microsoft.VisualStudio.ComponentGroup.NativeDesktop.Core --add Microsoft.VisualStudio.Workload.MSBuildTools --add Microsoft.VisualStudio.Workload.VCTools + +Install pixi +^^^^^^^^^^^^ + +Continue using the previous powershell session, and use the instructions on https://pixi.sh/latest/ to install ``pixi``. + +Install dependencies +^^^^^^^^^^^^^^^^^^^^ + +Download the pixi configuration file in the existing powershell session: + +.. code-block:: console + + cd C:\dev + irm https://raw.githubusercontent.com/ros2/ros2/refs/heads/{REPOS_FILE_BRANCH}/pixi.toml -OutFile pixi.toml + +Install dependencies: - pip install -U colcon-common-extensions coverage flake8 flake8-blind-except flake8-builtins flake8-class-newline flake8-comprehensions flake8-deprecated flake8-import-order flake8-quotes mock mypy==0.931 pytest pytest-cov pytest-mock pytest-repeat pytest-rerunfailures pytest-runner vcstool +.. code-block:: console + + pixi install Build ROS 2 ----------- +Source the pixi environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This is required in every command shell you open to set up paths to the dependencies: + +.. code-block:: console + + cd C:\dev + pixi shell + Get ROS 2 code ^^^^^^^^^^^^^^ Now that we have the development tools we can get the ROS 2 source code. -First setup a development folder, for example ``C:\{DISTRO}``: +Setup a development folder, for example ``C:\dev\{DISTRO}``: .. note:: @@ -60,8 +108,8 @@ First setup a development folder, for example ``C:\{DISTRO}``: .. code-block:: bash - md \{DISTRO}\src - cd \{DISTRO} + md C:\dev\{DISTRO}\src + cd C:\dev\{DISTRO} Get the ``ros2.repos`` file which defines the repositories to clone from: @@ -80,8 +128,6 @@ Build the code in the workspace .. _windows-dev-build-ros2: -To build ROS 2 you will need a Visual Studio Command Prompt ("x64 Native Tools Command Prompt for VS 2019") running as Administrator. - To build the ``\{DISTRO}`` folder tree: .. code-block:: bash @@ -93,11 +139,6 @@ To build the ``\{DISTRO}`` folder tree: We're using ``--merge-install`` here to avoid a ``PATH`` variable that is too long at the end of the build. If you're adapting these instructions to build a smaller workspace then you might be able to use the default behavior which is isolated install, i.e. where each package is installed to a different folder. -.. note:: - - If you are doing a debug build use ``python_d path\to\colcon_executable`` ``colcon``. - See `Extra stuff for debug mode`_ for more info on running Python code in debug builds on Windows. - Setup environment ----------------- @@ -105,7 +146,7 @@ Start a command shell and source the ROS 2 setup file to set up the workspace: .. code-block:: bash - call C:\{DISTRO}\install\local_setup.bat + call C:\dev\{DISTRO}\install\local_setup.bat This will automatically set up the environment for any DDS vendors that support was built for. @@ -160,84 +201,6 @@ Next steps Continue with the :doc:`tutorials and demos <../../Tutorials>` to configure your environment, create your own workspace and packages, and learn ROS 2 core concepts. -Extra stuff for Debug mode --------------------------- - -If you want to be able to run all the tests in Debug mode, you'll need to install a few more things: - -* To be able to extract the Python source tarball, you can use PeaZip: - -.. code-block:: bash - - choco install -y peazip - -* You'll also need SVN, since some of the Python source-build dependencies are checked out via SVN: - -.. code-block:: bash - - choco install -y svn hg - -* You'll need to quit and restart the command prompt after installing the above. -* Get and extract the Python 3.8.3 source from the ``tgz``: - - * https://www.python.org/ftp/python/3.8.3/Python-3.8.3.tgz - * To keep these instructions concise, please extract it to ``C:\dev\Python-3.8.3`` - -* Now, build the Python source in debug mode from a Visual Studio command prompt: - -.. code-block:: bash - - cd C:\dev\Python-3.8.3\PCbuild - get_externals.bat - build.bat -p x64 -d - -* Finally, copy the build products into the Python38 installation directories, next to the Release-mode Python executable and DLL's: - -.. code-block:: bash - - cd C:\dev\Python-3.8.3\PCbuild\amd64 - copy python_d.exe C:\Python38 /Y - copy python38_d.dll C:\Python38 /Y - copy python3_d.dll C:\Python38 /Y - copy python38_d.lib C:\Python38\libs /Y - copy python3_d.lib C:\Python38\libs /Y - copy sqlite3_d.dll C:\Python38\DLLs /Y - for %I in (*_d.pyd) do copy %I C:\Python38\DLLs /Y - -* Now, from a fresh command prompt, make sure that ``python_d`` works: - -.. code-block:: bash - - python_d -c "import _ctypes ; import coverage" - -* Once you have verified the operation of ``python_d``, it is necessary to reinstall a few dependencies with the debug-enabled libraries: - -.. code-block:: bash - - python_d -m pip install --force-reinstall https://github.com/ros2/ros2/releases/download/numpy-archives/numpy-1.18.4-cp38-cp38d-win_amd64.whl - python_d -m pip install --force-reinstall https://github.com/ros2/ros2/releases/download/lxml-archives/lxml-4.5.1-cp38-cp38d-win_amd64.whl - -* To verify the installation of these dependencies: - -.. code-block:: bash - - python_d -c "from lxml import etree ; import numpy" - -* When you wish to return to building release binaries, it is necessary to uninstall the debug variants and use the release variants: - -.. code-block:: bash - - python -m pip uninstall numpy lxml - python -m pip install numpy lxml - -* To create executables python scripts(.exe), python_d should be used to invoke colcon - -.. code-block:: bash - - python_d path\to\colcon_executable build - -* Hooray, you're done! - Stay up to date --------------- @@ -258,4 +221,4 @@ Uninstall .. code-block:: bash - rmdir /s /q \ros2_{DISTRO} + rmdir /s /q C:\dev\ros2_{DISTRO} diff --git a/source/Installation/Windows-Install-Binary.rst b/source/Installation/Windows-Install-Binary.rst index 0b175e08601..5954255edec 100644 --- a/source/Installation/Windows-Install-Binary.rst +++ b/source/Installation/Windows-Install-Binary.rst @@ -20,7 +20,46 @@ Only Windows 10 is supported. .. _windows-install-binary-installing-prerequisites: -.. include:: _Windows-Install-Prerequisites.rst +Create a location for the ROS 2 installation +-------------------------------------------- + +This location will contain both the installed binary packages, plus the ROS 2 installation itself. + +Start a powershell session (usually by clicking on the start menu, then typing ``powershell``). + +Then create a directory to store the installation. +Because of Windows path-length limitations, this should be as short as possible. +We'll use ``C:\dev`` for the rest of these instructions. + +.. code-block:: console + + md C:\dev + +Install prerequisites +--------------------- + +ROS 2 uses `conda-forge `__ as a backend for packages, with `pixi `__ as the frontend. + +Install pixi +^^^^^^^^^^^^ + +Continue using the previous powershell session, and use the instructions on https://pixi.sh/latest/ to install ``pixi``. + +Install dependencies +^^^^^^^^^^^^^^^^^^^^ + +Download the pixi configuration file in the existing powershell session: + +.. code-block:: console + + cd C:\dev + irm https://raw.githubusercontent.com/ros2/ros2/refs/heads/{REPOS_FILE_BRANCH}/pixi.toml -OutFile pixi.toml + +Install dependencies: + +.. code-block:: console + + pixi install Install ROS 2 ------------- @@ -34,12 +73,7 @@ Instead you may download nightly :ref:`prerelease binaries There may be more than one binary download option which might cause the file name to differ. -.. note:: - - To install debug libraries for ROS 2, see `Extra Stuff for Debug`_. - Then continue on with downloading ``ros2-package-windows-debug-AMD64.zip``. - -* Unpack the zip file somewhere (we'll assume ``C:\dev\ros2_{DISTRO}``\ ). +* Unpack the zip file somewhere (we'll assume ``C:\dev\ros2_{DISTRO}``). Install additional RMW implementations (optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -51,11 +85,19 @@ See the :doc:`guide <../How-To-Guides/Working-with-multiple-RMW-implementations> Setup environment ----------------- -Start a command shell and source the ROS 2 setup file to set up the workspace: +Start a command shell or powershell. +Source the pixi environment to set up dependencies: -.. code-block:: bash +.. code-block:: console + + cd C:\dev + pixi shell + +Now source the ROS 2 setup file to set up the workspace: - call C:\dev\ros2_{DISTRO}\local_setup.bat +.. code-block:: console + + call ros2_{DISTRO}\local_setup.bat It is normal that the previous command, if nothing else went wrong, outputs "The system cannot find the path specified." exactly once. @@ -99,32 +141,4 @@ Uninstall .. code-block:: bash - rmdir /s /q \ros2_{DISTRO} - -Extra Stuff for Debug ---------------------- - -To download the ROS 2 debug libraries you'll need to download ``ros2-{DISTRO}-*-windows-debug-AMD64.zip``. -Please note that debug libraries require some more additional configuration/setup to work as given below. - -Python installation may require modification to enable debugging symbols and debug binaries: - -* Search in windows **Search Bar** and open **Apps and Features**. -* Search for the installed Python version. - -* Click Modify. - - .. image:: images/python_installation_modify.png - :width: 500 px - -* Click Next to go to **Advanced Options**. - - .. image:: images/python_installation_next.png - :width: 500 px - -* Make sure **Download debugging symbols** and **Download debug binaries** are checked. - - .. image:: images/python_installation_enable_debug.png - :width: 500 px - -* Click Install. + rmdir /s /q C:\dev diff --git a/source/Installation/_Windows-Install-Prerequisites.rst b/source/Installation/_Windows-Install-Prerequisites.rst deleted file mode 100644 index 095daa12da0..00000000000 --- a/source/Installation/_Windows-Install-Prerequisites.rst +++ /dev/null @@ -1,166 +0,0 @@ -System setup ------------- - -Install Chocolatey -^^^^^^^^^^^^^^^^^^ - -Chocolatey is a package manager for Windows, install it by following their installation instructions: - -https://chocolatey.org/install - -You'll use Chocolatey to install some other developer tools. - -Install Python -^^^^^^^^^^^^^^ - -Open a Command Prompt and type the following to install Python via Chocolatey: - -.. code-block:: bash - - choco install -y python --version 3.8.3 - -.. note:: - - Chocolatey will install Python in ``C:\Python38``, and the rest of the installation expects it to be there. - If you've installed Python somewhere else, you must copy or link it to that location. - -Install Visual C++ Redistributables -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Open a Command Prompt and type the following to install them via Chocolatey: - -.. code-block:: bash - - choco install -y vcredist2013 vcredist140 - -Install OpenSSL -^^^^^^^^^^^^^^^ - -Open a Command Prompt and type the following to install OpenSSL via Chocolatey: - -.. code-block:: bash - - choco install -y openssl --version 1.1.1.2100 - -This command sets an environment variable that persists over sessions: - -.. code-block:: bash - - setx /m OPENSSL_CONF "C:\Program Files\OpenSSL-Win64\bin\openssl.cfg" - -You will need to append the OpenSSL-Win64 bin folder to your PATH. -You can do this by clicking the Windows icon, typing "Environment Variables", then clicking on "Edit the system environment variables". -In the resulting dialog, click "Environment Variables", then click "Path" on the bottom pane, finally click "Edit" and add the path below. - -* ``C:\Program Files\OpenSSL-Win64\bin\`` - -Install Visual Studio -^^^^^^^^^^^^^^^^^^^^^ - -Install Visual Studio 2019. - -If you already have a paid version of Visual Studio 2019 (Professional, Enterprise), skip this step. - -Microsoft provides a free of charge version of Visual Studio 2019, named Community, which can be used to build applications that use ROS 2. -`You can download the installer directly through this link. `_ - -Make sure that the Visual C++ features are installed. - -An easy way to make sure they're installed is to select the ``Desktop development with C++`` workflow during the install. - - .. image:: /Installation/images/windows-vs-studio-install.png - -Make sure that no C++ CMake tools are installed by unselecting them in the list of components to be installed. - -Install OpenCV -^^^^^^^^^^^^^^ - -Some of the examples require OpenCV to be installed. - -You can download a precompiled version of OpenCV 3.4.6 from https://github.com/ros2/ros2/releases/download/opencv-archives/opencv-3.4.6-vc16.VS2019.zip . - -Assuming you unpacked it to ``C:\opencv``, type the following on a Command Prompt (requires Admin privileges): - -.. code-block:: bash - - setx /m OpenCV_DIR C:\opencv - -Since you are using a precompiled ROS version, we have to tell it where to find the OpenCV libraries. -You have to extend the ``PATH`` variable to ``C:\opencv\x64\vc16\bin``. - -Install dependencies -^^^^^^^^^^^^^^^^^^^^ - -There are a few dependencies not available in the Chocolatey package database. -In order to ease the manual installation process, we provide the necessary Chocolatey packages. - -As some chocolatey packages rely on it, we start by installing CMake - -.. code-block:: bash - - choco install -y cmake - -You will need to append the CMake bin folder ``C:\Program Files\CMake\bin`` to your PATH. - -Please download these packages from `this `__ GitHub repository. - -* asio.1.12.1.nupkg -* bullet.3.17.nupkg -* cunit.2.1.3.nupkg -* eigen.3.3.4.nupkg -* tinyxml2.6.0.0.nupkg - -Once these packages are downloaded, open an administrative shell and execute the following command: - -.. code-block:: bash - - choco install -y -s asio cunit eigen tinyxml2 bullet - -Please replace ```` with the folder you downloaded the packages to. - -First upgrade pip and setuptools: - -.. code-block:: bash - - python -m pip install -U pip setuptools==59.6.0 - -Now install some additional python dependencies: - -.. code-block:: bash - - python -m pip install -U catkin_pkg cryptography empy fastjsonschema==2.19.0 importlib-metadata jsonschema lark==1.1.1 lxml matplotlib netifaces numpy opencv-python PyQt5 pillow psutil pycairo pydot pyparsing==2.4.7 pytest pyyaml rosdistro - -Install miscellaneous prerequisites -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Next install xmllint: - -* Download the `64 bit binary archives `__ of ``libxml2`` (and its dependencies ``iconv`` and ``zlib``) from https://www.zlatkovic.com/projects/libxml/ -* Unpack all archives into e.g. ``C:\xmllint`` -* Add ``C:\xmllint\bin`` to the ``PATH``. - -Install Qt5 -^^^^^^^^^^^ - -Download the `5.12.X offline installer `_ from Qt's website. -Run the installer. -Make sure to select the ``MSVC 2017 64-bit`` component under the ``Qt`` -> ``Qt 5.12.12`` tree. - -Finally, in an administrator ``cmd.exe`` window set these environment variables. -The commands below assume you installed it to the default location of ``C:\Qt``. - -.. code-block:: bash - - setx /m Qt5_DIR C:\Qt\Qt5.12.12\5.12.12\msvc2017_64 - setx /m QT_QPA_PLATFORM_PLUGIN_PATH C:\Qt\Qt5.12.12\5.12.12\msvc2017_64\plugins\platforms - - -.. note:: - - This path might change based on the installed MSVC version, the directory Qt was installed to, and the version of Qt installed. - -RQt dependencies -^^^^^^^^^^^^^^^^ - -To run rqt_graph you need to `download `__ and install `Graphviz `__. -The installer will ask if to add graphviz to PATH, choose to either add it to the current user or all users.