Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve Windows Installation instructions #381

Merged
merged 8 commits into from
Sep 19, 2023
Merged

Improve Windows Installation instructions #381

Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
6f2f1eb
Improve Windows Installation instructions
peci1 Sep 3, 2023
30fd6a8
Added installation of gz-tools2 to Windows instructions.
peci1 Sep 3, 2023
a39f8a0
Update Windows install tutorial
peci1 Sep 3, 2023
8c39de0
Removed mention of ROS from Windows install instructions
peci1 Sep 15, 2023
ab0cf96
indent fixes to original page
mabelzhang Sep 16, 2023
295b300
more indent
mabelzhang Sep 16, 2023
2b49a53
Apply suggestions from code review
peci1 Sep 16, 2023
6b36809
Turned some WARNINGs into NOTEs.
peci1 Sep 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
148 changes: 97 additions & 51 deletions harmonic/install_windows_src.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,14 @@ WARNING: Current Windows support is experimental.

# Source Installation on Windows 10 or 11

Command line tools, DART physics engine, and GUI capabilities are
not currently supported in Windows. These functionalities correspond to the currently
building packages `gz-tools`, `gz-physics`, and `gz-gui`, respectively.
OGRE2 rendering capabilities are not currently supported in Windows, and Gazebo GUI
works in a limited fashion. These functionalities correspond to the currently
building packages `gz-rendering` and `gz-sim`, respectively. The packages will build,
but you can expect runtime failures when using their functionalities.
peci1 marked this conversation as resolved.
Show resolved Hide resolved

**Note**

You will still be able to use `TPE` as a physics engine
(see [here](https://gazebosim.org/api/physics/2.2/physicsplugin.html) for more information on `TPE`).
> [!NOTE]
peci1 marked this conversation as resolved.
Show resolved Hide resolved
> You should be able to use `ogre` as a rendering engine instead of the default `ogre2`.
> Just append `--render-engine ogre` to the command line.

## Install dependencies

Expand All @@ -20,62 +20,74 @@ You will still be able to use `TPE` as a physics engine
You will likely want to check the box to add `conda` to your `PATH`
during the installation process so that you won't have to do this step manually.

2. Install [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/).
2. Install [Visual Studio 2019 or 2022](https://visualstudio.microsoft.com/downloads/).
The Community version is free for students, open-source developers, and personal
development. Check "Desktop development with C++" in the Workloads tab,
check "MFC and ATL support", and uncheck "C++ Cmake Tools." We will install
cmake via Conda.
cmake via Conda. All other checkboxes can be left unchecked.

3. Open a Visual Studio Command Prompt (search for "x64 Native Tools Command Prompt
for VS 2019" in the Windows search field near the Windows button). Optionally,
for VS" in the Windows search field near the Windows button). Optionally,
right-click and pin to the task bar for quick access in the future.

If you did not add Conda to your `PATH` environment variable during Conda installation,
you may need to navigate to the location of `condabin` in order to use the `conda` command.
To find `condabin`, search for "Anaconda Prompt" in the Windows search field near the
Windows button, open it, run `where conda`, and look for a line containing the directory `condabin`.
If you did not add Conda to your `PATH` environment variable during Conda installation,
you may need to navigate to the location of `condabin` in order to use the `conda` command.
To find `condabin`, search for "Anaconda Prompt" in the Windows search field near the
Windows button, open it, run `where conda`, and look for a line containing the directory `condabin`.

4. Navigate to your `condabin`, if necessary, and then create and activate a Conda environment:
```bash
conda create -n gz-ws
conda activate gz-ws
```

Once you have activate an environment, a prefix like `(gz-ws)` will be prepended to
your prompt, and you can use the `conda` command outside of the `condabin` directory.

You can use `conda info --envs` to see all of your environments.

To remove an environment, use `conda env remove --name <env_name>`.
```bash
conda create -n gz-ws
conda activate gz-ws
```
Once you have activated an environment, a prefix like `(gz-ws)` will be prepended to
your prompt, and you can use the `conda` command outside of the `condabin` directory.

You can use `conda info --envs` to see all of your environments.

To speed up conda installations, also set the following to use libmamba solver.
Older conda installations may need to do [additional steps](https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community).
```bash
conda config --set solver libmamba
```
To remove an environment, use `conda remove --all --name <env_name>`.

> [!NOTE]
peci1 marked this conversation as resolved.
Show resolved Hide resolved
> This way of Conda environment creation puts it into a default folder. If you need
to install it elsewhere, use `--prefix <env_path>` instead of `--name <env_name>`.
Environments in custom paths cannot be referenced by names, so even `conda activate`
needs to be passed a path (relative or absolute) instead of the name. If you refer
to a subdirectory of the current directory, you have to prepend `.\` so that Conda
knows it is a path and not a name.

5. Install dependencies:

```bash
conda install cmake git vcstool curl pkg-config ^
colcon-common-extensions dartsim eigen freeimage gdal gts ^
glib dlfcn-win32 ffmpeg ruby tinyxml2 tinyxml ^
libprotobuf urdfdom zeromq cppzmq ogre ogre-next jsoncpp ^
libzip qt pybind11 --channel conda-forge
```
```bash
conda install cmake git vcstool curl pkg-config ^
colcon-common-extensions dartsim eigen freeimage gdal gts ^
glib dlfcn-win32 ffmpeg ruby tinyxml2 tinyxml ^
libprotobuf urdfdom zeromq cppzmq ogre=1.10 ogre-next jsoncpp ^
libzip qt pybind11 --channel conda-forge
```
This can take tens of minutes (or less when using libmamba solver).
peci1 marked this conversation as resolved.
Show resolved Hide resolved

6. Navigate to where you would like to build the library, create and enter your workspace directory,
create the `src` directory which will contain the Gazebo source code.
```bash
mkdir gz-ws
cd gz-ws
mkdir src
```
```bash
mkdir gz-ws
cd gz-ws
mkdir src
```

7. Then clone the repositories
```bash
# CMD
curl -sk https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-harmonic.yaml -o collection-harmonic
vcs import src < collection-harmonic
```bash
# CMD
curl -sk https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-harmonic.yaml -o collection-harmonic
vcs import src < collection-harmonic

# PowerShell
curl https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-harmonic.yaml -o collection-harmonic
vcs import --input collection-harmonic src
```
# PowerShell
curl https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-harmonic.yaml -o collection-harmonic
vcs import --input collection-harmonic src
```

## Building the Gazebo Libraries

Expand All @@ -92,13 +104,10 @@ colcon graph
If that is the case, then you are ready to build the whole set of libraries:

```bash
colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install --packages-up-to gz-sim8
colcon build --cmake-args -DBUILD_TESTING=OFF --merge-install --packages-up-to gz-sim8 gz-tools2
```
Tests are turned off as they are not currently supported on Windows.

**Note:** All of the Gazebo packages up to, but not including `gz-sim`
are currently building. The above command should successfully build all packages except for `gz-sim`.

To build a specific package with all its dependent packages:

```bash
Expand All @@ -117,7 +126,8 @@ If there are no errors, all the binaries should be ready to use.

## Using the workspace

The workspace needs to be sourced every time a new terminal is used.
The workspace needs to be sourced every time a new terminal is used (
and Conda environment activated before that).

Run the following command to source the workspace:

Expand All @@ -132,6 +142,34 @@ call install\setup.bat
This is the end of the source install instructions; head back to the [Getting started](/docs/all/getstarted)
page to start using Gazebo!

> [!WARNING]
> As Gazebo GUI is not yet working, running `gz sim` will not work. You can run only the server with

```cmd
gz sim -s -v
```
peci1 marked this conversation as resolved.
Show resolved Hide resolved

> [!WARNING]
> If you username contains spaces (which is quite common on Windows), you will probably get errors
saying `Invalid partition name [Computer:My User With Spaces]`. Fix this by changing `GZ_PARTITION`
to something else:

```cmd
set GZ_PARTITION=test
```

Remember to set the same partition in all other consoles.
peci1 marked this conversation as resolved.
Show resolved Hide resolved

### Gazebo GUI workaround

Although running `gz sim` without arguments is not supported on Windows,
and `gz sim -g` is also not supported, there is a workaround you can apply
to be able to launch `gz sim -g` on Windows.

> Manually comment [these lines](https://github.com/gazebosim/gz-sim/blob/gz-sim7_7.5.0/src/cmd/cmdsim.rb.in#L497-L501) and [these lines](https://github.com/gazebosim/gz-sim/blob/gz-sim7_7.5.0/src/cmd/cmdsim.rb.in#L558-L562) in file `install\lib\ruby\gz\cmdsim8.rb`.

This should allow you to run the GUI in a separate console, connecting to the server running in another console.

## Uninstalling source-based install

A source-based install can be "uninstalled" using several methods, depending on
Expand All @@ -153,6 +191,14 @@ the results you want:
3. If you want to keep the source code, you can remove the
`install` / `build` / `log` directories as desired, leaving the `src` directory.

4. Last, if you do not need the conda environment anymore, you can remove it with

```bash
conda deactivate
conda remove --all --name <env_name>
# or conda remove --all --prefix <path_to_env> if you installed to custom path
```

## Troubleshooting

See [Troubleshooting](/docs/harmonic/troubleshooting#windows)
Loading