.. redirect-from:: Installation/Windows-Development-Setup Windows (source) ================ .. contents:: Table of Contents :depth: 2 :local: This guide is about how to setup a development environment for ROS 2 on Windows. System requirements ------------------- Only Windows 10 is supported. 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 Install additional prerequisites from Chocolatey ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: bash choco install -y cppcheck curl git winflexbison3 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). Install Python prerequisites ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Install additional Python dependencies: .. code-block:: bash 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-mock vcstool Build ROS 2 ----------- 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 https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation?tabs=registry. .. code-block:: bash md \{DISTRO}\src cd \{DISTRO} Get the ``ros2.repos`` file which defines the repositories to clone from: .. code-block:: bash vcs import --input https://raw.githubusercontent.com/ros2/ros2/{REPOS_FILE_BRANCH}/ros2.repos src Install additional RMW implementations (optional) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The default middleware that ROS 2 uses is ``Fast DDS``, but the middleware (RMW) can be replaced at build or runtime. See the :doc:`guide <../../How-To-Guides/Working-with-multiple-RMW-implementations>` on how to work with multiple RMWs. 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 colcon build --merge-install .. note:: 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 This will automatically set up the environment for any DDS vendors that support was built for. It is normal that the previous command, if nothing else went wrong, outputs "The system cannot find the path specified." exactly once. Try some examples ----------------- Note that the first time you run any executable you will have to allow access to the network through a Windows Firewall popup. You can run the tests using this command: .. code-block:: bash colcon test --merge-install .. note:: ``--merge-install`` should only be used if it was also used in the build step. Afterwards you can get a summary of the tests using this command: .. code-block:: bash colcon test-result To run the examples, first open a clean new ``cmd.exe`` and set up the workspace by sourcing the ``local_setup.bat`` file. Then, run a C++ ``talker``\ : .. code-block:: bash 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``\ : .. code-block:: bash call install\local_setup.bat ros2 run demo_nodes_py listener You should see the ``talker`` saying that it's ``Publishing`` messages and the ``listener`` saying ``I heard`` those messages. This verifies both the C++ and Python APIs are working properly. Hooray! .. note:: It is not recommended to build in the same cmd prompt that you've sourced the ``local_setup.bat``. 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 --------------- See :doc:`../Maintaining-a-Source-Checkout` to periodically refresh your source installation. Troubleshoot ------------ Troubleshooting techniques can be found :ref:`here `. Uninstall --------- 1. If you installed your workspace with colcon as instructed above, "uninstalling" could be just a matter of opening a new terminal and not sourcing the workspace's ``setup`` file. This way, your environment will behave as though there is no {DISTRO_TITLE} install on your system. 2. If you're also trying to free up space, you can delete the entire workspace directory with: .. code-block:: bash rmdir /s /q \ros2_{DISTRO}