Skip to content

Commit

Permalink
Cleanup the Windows instructions for using conda/pixi.
Browse files Browse the repository at this point in the history 
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 <[email protected]>
  • Loading branch information
@clalancette
clalancette committed Feb 3, 2025
1 parent 49f66fd commit 9d08105
Show file tree
Hide file tree
Showing 3 changed files with 119 additions and 308 deletions.
169 changes: 66 additions & 103 deletions source/Installation/Alternatives/Windows-Development-Setup.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------------------
Expand All @@ -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 <https://support.microsoft.com/en-us/windows/language-packs-for-windows-a5094319-a92d-18de-5b53-1cfc697cfca8>`_.

.. 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 <https://conda-forge.org/>`__ as a backend for packages, with `pixi <https://pixi.sh/latest/>`__ 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::

Expand All @@ -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:

Expand All @@ -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
Expand All @@ -93,19 +139,14 @@ 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
-----------------

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.

Expand Down Expand Up @@ -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
---------------

Expand All @@ -258,4 +221,4 @@ Uninstall

.. code-block:: bash
rmdir /s /q \ros2_{DISTRO}
rmdir /s /q C:\dev\ros2_{DISTRO}
92 changes: 53 additions & 39 deletions source/Installation/Windows-Install-Binary.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://conda-forge.org/>`__ as a backend for packages, with `pixi <https://pixi.sh/latest/>`__ 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
-------------
Expand All @@ -34,12 +73,7 @@ Instead you may download nightly :ref:`prerelease binaries <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)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -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.

Expand Down Expand Up @@ -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
Loading

0 comments on commit 9d08105

Please sign in to comment.