Update Windows install guide Change-Id: I445354bee0f54b33921ea9411b7bb320af275d43
diff --git a/docs/source/installation.rst b/docs/source/installation.rst index 182bfd2..a59b15b 100644 --- a/docs/source/installation.rst +++ b/docs/source/installation.rst
@@ -21,10 +21,9 @@ Dependencies ============ - .. NOTE :: + .. note :: - Starting with v2.0 Ceres requires a **fully C++14-compliant** - compiler. In versions <= 1.14, C++11 was an optional requirement. + Ceres Solver 2.1 requires a **fully C++14-compliant** compiler. Ceres relies on a number of open source libraries, some of which are optional. For details on customizing the build process, see @@ -69,7 +68,7 @@ examples and tests and usually a dependency for glog. - `SuiteSparse <http://faculty.cse.tamu.edu/davis/suitesparse.html>`_ - 5.0 or later. Needed for solving large sparse linear + 4.0 or later. Needed for solving large sparse linear systems. **Optional; strongly recomended for large scale bundle adjustment** @@ -319,8 +318,8 @@ equivalent on Microsoft Windows and can be used to install Ceres Solver. -If building from source on Windows, we support building with Visual -Studio 2015.2 of newer. +Ceres Solver can also be built from source. For this purpose, we support Visual +Studio 2019 and newer. .. NOTE:: @@ -329,10 +328,11 @@ <https://github.com/tbennun/ceres-windows>`_ for Ceres Solver by Tal Ben-Nun. -#. Make a toplevel directory for deps & build & src somewhere: ``ceres/`` +#. Create a top-level directory for dependencies, build, and sources somewhere, + e.g., ``ceres/`` #. Get dependencies; unpack them as subdirectories in ``ceres/`` - (``ceres/eigen``, ``ceres/glog``, etc) + (``ceres/eigen``, ``ceres/glog``, etc.) #. ``Eigen`` 3.3 . Configure and optionally install Eigen. It should be exported into the CMake package registry by default as part of the @@ -355,6 +355,17 @@ wish to use ``CXSparse``, follow their instructions for obtaining and building it. + #. Alternatively, Ceres Solver supports ``SuiteSparse`` binary + packages available for Visual Studio 2019 and 2022 provided by the `CMake + support for SuiteSparse <https://github.com/sergiud/SuiteSparse>`_ project + that also include `reference LAPACK <http://www.netlib.org/blas>`_ (and + BLAS). The binary packages are used by Ceres Solver for continuous testing + on Github. + + .. note:: + + The GPL licensed version of the SuiteSparse package is required. + #. Unpack the Ceres tarball into ``ceres``. For the tarball, you should get a directory inside ``ceres`` similar to ``ceres-solver-2.1.0``. Alternately, checkout Ceres via ``git`` to @@ -362,27 +373,40 @@ #. Install ``CMake``, -#. Make a dir ``ceres/ceres-bin`` (for an out-of-tree build) +#. Create a directory ``ceres/ceres-bin`` (for an out-of-tree build) + + #. If you use the above binary ``SuiteSparse`` package, make sure CMake can + find it, e.g., by assigning the path of the directory that contains the + unzipped contents to the ``CMAKE_PREFIX_PATH`` environment variable. In a + Windows command prompt this can be achieved as follows: + + .. code:: bat + + export CMAKE_PREFIX_PATH=C:/Downloads/SuiteSparse-5.11.0-cmake.1-vc16-Win64-Release-shared-gpl #. Run ``CMake``; select the ``ceres-solver-X.Y.Z`` or ``ceres-solver.git`` directory for the CMake file. Then select the - ``ceres-bin`` for the build dir. + ``ceres-bin`` for the build directory. -#. Try running ``Configure``. It won't work. It'll show a bunch of options. - You'll need to set: +#. Try running ``Configure`` which can fail at first because some dependencies + cannot be automatically located. In this case, you must set the following + CMake variables to the appropriate directories where you unpacked/built them: #. ``Eigen3_DIR`` (Set to directory containing ``Eigen3Config.cmake``) #. ``GLOG_INCLUDE_DIR_HINTS`` #. ``GLOG_LIBRARY_DIR_HINTS`` #. (Optional) ``gflags_DIR`` (Set to directory containing ``gflags-config.cmake``) + #. (SuiteSparse binary package) ``BLAS_blas_LIBRARY`` and + ``LAPACK_lapack_LIBRARY`` CMake variables must be `explicitly set` to + ``<path>/lib/blas.lib`` and ``<path>/lib/lapack.lib``, respectively, both + located in the unzipped package directory ``<path>``. - to the appropriate directories where you unpacked/built them. If - any of the variables are not visible in the ``CMake`` GUI, create a - new entry for them. We recommend using the - ``<NAME>_(INCLUDE/LIBRARY)_DIR_HINTS`` variables rather than - setting the ``<NAME>_INCLUDE_DIR`` & ``<NAME>_LIBRARY`` variables - directly to keep all of the validity checking, and to avoid having - to specify the library files manually. + If any of the variables are not visible in the ``CMake`` GUI, create a new + entry for them. We recommend using the + ``<NAME>_(INCLUDE/LIBRARY)_DIR_HINTS`` variables rather than setting the + ``<NAME>_INCLUDE_DIR`` & ``<NAME>_LIBRARY`` variables directly to keep all of + the validity checking, and to avoid having to specify the library files + manually. #. You may have to tweak some more settings to generate a MSVC project. After each adjustment, try pressing Configure & Generate @@ -397,17 +421,14 @@ Like the Linux build, you should now be able to run ``bin/simple_bundle_adjuster``. -Notes: +.. note:: -#. The default build is Debug; consider switching it to release mode. -#. Currently ``system_test`` is not working properly. -#. CMake puts the resulting test binaries in ``ceres-bin/examples/Debug`` - by default. -#. The solvers supported on Windows are ``DENSE_QR``, ``DENSE_SCHUR``, - ``CGNR``, and ``ITERATIVE_SCHUR``. -#. We're looking for someone to work with upstream ``SuiteSparse`` to - port their build system to something sane like ``CMake``, and get a - fully supported Windows port. + #. The default build is ``Debug``; consider switching it to ``Release`` for + optimal performance. + #. CMake puts the resulting test binaries in ``ceres-bin/examples/Debug`` by + default. + #. Without ``SuiteSparse``, only a subset of solvers is usable, + namely: ``DENSE_QR``, ``DENSE_SCHUR``, ``CGNR``, and ``ITERATIVE_SCHUR``. .. _section-android: