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

Update installation and build documentation for Windows & Python on Windows #2000

Merged
merged 1 commit into from
Jan 25, 2025
Merged

Update installation and build documentation for Windows & Python on Windows #2000

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
25 changes: 23 additions & 2 deletions INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,7 @@ This section details how to build a GTSAM `.sln` file using Visual Studio.
### Prerequisites

- Visual Studio with C++ CMake tools for Windows
- CMake >= 3.21 is required for Visual Studio installation because custom templates used in the build were added in 3.21. Use `cmake --version` in the VS Developer Command Prompt to ensure you meet this requirement.
- All the other pre-requisites listed above.

### Steps
Expand All @@ -97,13 +98,33 @@ This section details how to build a GTSAM `.sln` file using Visual Studio.
- Set the `Toolset` to `msvc_x64_x64`. If you know what toolset you require, then skip this step.
- Update the `Build root` to `${projectDir}\build\${name}`.
- You can optionally create a new configuration for a `Release` build.
- Set the necessary CMake variables for your use case.
- Set the necessary CMake variables for your use case. If you are not using Boost, uncheck `GTSAM_ENABLE_BOOST_SERIALIZATION` and `GTSAM_USE_BOOST_FEATURES`.
- Click on `Show advanced settings`.
- For `CMake generator`, select a version which matches `Visual Studio <Version> <Year> Win64`, e.g. `Visual Studio 16 2019 Win64`.
- Save the settings (Ctrl + S).
4. Click on `Project -> Generate Cache`. This will generate the CMake build files (as seen in the Output window).
4. Saving the CMake settings should automatically generate the cache. Otherwise, click on `Project -> Generate Cache`. This will generate the CMake build files (as seen in the Output window).
- If generating the cache yields `CMake Error ... (ADD_CUSTOM_COMMAND)` errors, you have an old CMake. Verify that your CMake is >= 3.21. If Visual Studio says that it is but you're still getting the error, install the latest CMake (tested with 3.31.4) and point to its executable in `CMakeSettings > Advanced settings > CMake executable`.
5. The last step will generate a `GTSAM.sln` file in the `build` directory. At this point, GTSAM can be used as a regular Visual Studio project.

### Python Installation

To install the Python bindings on Windows:

Install [pyparsing(>=2.4.2)](https://github.com/pyparsing/pyparsing), [pybind-stubgen>=2.5.1](https://github.com/sizmailov/pybind11-stubgen) and [numpy(>=1.11.0)](https://numpy.org/) with the Python environment you wish to develop in. These can all be installed as follows:

```bash
pip install -r <gtsam_folder>/python/dev_requirements.txt
```

1. Follow the above steps for GTSAM general installation.
- In the CMake settings variables, set `GTSAM_BUILD_PYTHON` to be true and specify the path to your desired Python environment executable in the "CMake command arguments" field using `-DPYTHON_EXECUTABLE="<path to your python.exe>"`
- Once the cache is generated, ensure it's using your desired Python executable and the version is correct. It may cause errors later otherwise, such as missing Python packages required to build. If the version is not the one you specified in `DPYTHON_EXECUTABLE`, change the version in all 3 Python version specifiers in the CMake variables (`GTSAM_PYTHON_VERSION`, `PYBIND11_PYTHON_VERSION`, `WRAP_PYTHON_VERSION`) to the exact version of your desired executable. CMake might look for executables in the standard locations first, so ensure it's using the one you want before continuing.
2. Build the project (Build > Build All).
- If you encounter the error `C1083 Cannot open include file: 'boost/serialization/export.hpp': No such file or directory`, you need to make changes to the template files that include Boost since your build is not using Boost. Locate `python/gtsam/gtsam.tpl` (and `python/gtsam_unstable/gtsam_unstable.tpl` if you are building unstable) and comment out the line `#include <boost/serialization/export.hpp>` near the top of each. Delete the generated build directory (e.g. if you made `build/x64-Debug`, delete the `x64-Debug` folder), regenerate the cache, and build again.
- If you encounter an error involving copying `.pyd` files, find the files mentioned (`gtsam_py.pyd` and `gtsam_unstable_py.pyd`, probably in the `Debug`/`Release`/etc. folder inside `build/<your build>/python/gtsam`) and copy them to where they are supposed to be (the source of the copy error, probably `build/<your build>/python/gtsam`) then rebuild.
3. At this point, `gtsam` in `build/<your build>/python` is available to be used as a Python package. You can use `pip install .` in that directory to install the package.



# CMake Configuration Options and Details

Expand Down
4 changes: 4 additions & 0 deletions python/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,10 @@ For instructions on updating the version of the [wrap library](https://github.co

- You can also directly run `make python-install` without running `make`, and it will compile all the dependencies accordingly.

## Windows Installation

See Windows Installation in INSTALL.md in the root directory.

## Unit Tests

The Python toolbox also has a small set of unit tests located in the
Expand Down
Loading