Update Windows-Development-Setup.rst with pixi build instructions (backport ros2#4989)

Author: mikelikesrobots

source/Installation/Alternatives/Windows-Development-Setup.rst

@@ -9,59 +9,138 @@ 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
 -------------------
 
 Only Windows 10 is supported.
 
+.. warning::
+
+   We recommend using a clean Windows environment for the build, such as a fresh install, Docker container, or Virtual Machine. This is because existing software, such as other Python versions, can pollute the build configuration and cause compilation errors.
+
 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
+--------------------------------------------
+
+This location will contain both the installed binary packages, plus the ROS 2 installation itself.
 
-Install additional prerequisites from Chocolatey
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Start a powershell session (usually by clicking on the start menu, then typing ``powershell``).
 
-.. code-block:: bash
+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.
 
-   choco install -y cppcheck curl git winflexbison3
+.. code-block:: console
 
-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).
+   $ md C:\dev
 
-Install Python prerequisites
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Increase the Windows maximum path length
+----------------------------------------
+
+By default, Windows is restricted to a maximum path length (MAX_PATH) of 260 characters.
+The ROS 2 build will use significantly longer path lengths, so we will increase that.
+Using the powershell session you started above, run the following:
+
+.. code-block:: console
+
+   $ New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
+
+You can read more about this limitation in `Microsoft's documentation <https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry>`__.
+
+
+Install prerequisites
+---------------------
+
+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:
+
+.. 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
+
+.. note::
 
-Install additional Python dependencies:
+   The installation of MSVC can take a long time, and there is no feedback while it is progressing.
 
-.. code-block:: bash
+Install pixi
+^^^^^^^^^^^^
 
-   $ pip install -U colcon-common-extensions coverage flake8 flake8-blind-except flake8-builtins flake8-class-newline flake8-comprehensions flake8-deprecated flake8-docstrings flake8-import-order flake8-quotes mock mypy==0.931 pep8 pydocstyle pytest pytest-cov pytest-mock pytest-repeat pytest-rerunfailures pytest-runner vcstool
+ROS 2 uses `conda-forge <https://conda-forge.org/>`__ as a backend for packages, with `pixi <https://pixi.sh/latest/>`__ as the frontend.
+
+Continue using the previous powershell session, and use the instructions from https://pixi.sh/latest/ to install ``pixi``.
+Once ``pixi`` has been installed, close the powershell session and start it again, which will ensure ``pixi`` is on the PATH.
+
+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
+
+You should now close the powershell session, as the rest of the instructions will use the Windows command prompt.
 
 Build ROS 2
 -----------
 
+Start a new Windows command prompt, which will be used for the build.
+
+Source the MSVC compiler
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is required in the command prompt you'll use to compile ROS 2, but it is *not* required when running:
+
+.. code-block:: console
+
+  $ call "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x86_amd64
+
+Source the pixi environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is required in every command prompt 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}``:
-
-.. note::
-
-   It is very important that the chosen path is short, due to the short default Windows path limits (260 characters).
-   To allow longer paths, see `maximum-file-path-limitation <https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry>`__.
+Setup a development folder, for example ``C:\dev\{DISTRO}``:
 
 .. code-block:: console
 
-   $ 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 +159,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:: console
@@ -93,23 +170,33 @@ 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.
-
 .. note::
 
    Source installation can take a long time given the large number of packages being pulled into the workspace.
 
 Setup environment
 -----------------
 
-Start a command shell and source the ROS 2 setup file to set up the workspace:
+Start a new Windows command prompt, which will be used in the examples.
+
+Source the pixi environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is required in every command prompt you open to set up paths to the dependencies:
 
 .. code-block:: console
 
-   $ call C:\{DISTRO}\install\local_setup.bat
+   $ cd C:\dev
+   $ pixi shell
+
+Source the ROS 2 environment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is required in every command prompt you open to setup the ROS 2 workspace:
+
+.. code-block:: console
+
+   $ call C:\dev\{DISTRO}\install\local_setup.bat
 
 This will automatically set up the environment for any DDS vendors that support was built for.
 
@@ -144,7 +231,7 @@ Then, run a C++ ``talker``\ :
    $ call install\local_setup.bat
    $ ros2 run demo_nodes_cpp talker
 
-In a separate shell you can do the same, but instead run a Python ``listener``\ :
+In a separate command prompt you can do the same, but instead run a Python ``listener``\ :
 
 .. code-block:: console
 
@@ -164,84 +251,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``:
-
-  * `Python-3.8.3 <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
 ---------------
 
@@ -262,4 +271,4 @@ Uninstall
 
    .. code-block:: console
 
-      $ rmdir /s /q \ros2_{DISTRO}
+      $ rmdir /s /q C:\dev\{DISTRO}