Skip to content

Commit

Permalink
Improve Windows Installation instructions (#381)
Browse files Browse the repository at this point in the history 
* Improve Windows Installation instructions

Signed-off-by: Martin Pecka <[email protected]>

Signed-off-by: Martin Pecka <[email protected]>

* Added installation of gz-tools2 to Windows instructions.

Signed-off-by: Martin Pecka <[email protected]>

* Update Windows install tutorial

Signed-off-by: Martin Pecka <[email protected]>

* Removed mention of ROS from Windows install instructions

Signed-off-by: Martin Pecka <[email protected]>

* indent fixes to original page

Signed-off-by: Mabel Zhang <[email protected]>

* more indent

Signed-off-by: Mabel Zhang <[email protected]>

* Apply suggestions from code review

Co-authored-by: Mabel Zhang <[email protected]>
Signed-off-by: Martin Pecka <[email protected]>

* Turned some WARNINGs into NOTEs.

Signed-off-by: Martin Pecka <[email protected]>

---------

Signed-off-by: Martin Pecka <[email protected]>
Signed-off-by: Mabel Zhang <[email protected]>
Co-authored-by: Mabel Zhang <[email protected]>
Co-authored-by: Mabel Zhang <[email protected]>
  • Loading branch information
@peci1 @mabelzhang
3 people authored Sep 19, 2023
1 parent 8561d33 commit c6d09bd
Showing 1 changed file with 95 additions and 52 deletions.
147 changes: 95 additions & 52 deletions harmonic/install_windows_src.md
View file
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.

**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**
> 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**
> 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).

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,21 +126,47 @@ 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:

```bash
# CMD
call install\setup.bat
#PowerShell
# PowerShell
.\install\setup.ps1
```

This is the end of the source install instructions; head back to the [Getting started](/docs/all/getstarted)
page to start using Gazebo!

> **NOTE**
> 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
> ```

> **NOTE**
> If your 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.

### 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 +188,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)

0 comments on commit c6d09bd

Please sign in to comment.