doc: Consolidate build options in one place (#1360)

Author: AntoinePrv

CMakeLists.txt

@@ -46,7 +46,7 @@ target_compile_features(xsimd INTERFACE cxx_std_14)
 # developed or is vendored.
 # Otherwise (if an install is performed), this will be handled in the user
 # cmake script (xsimdConfig.cmake).
-if(ENABLE_XTL_COMPLEX)
+if(ENABLE_XTL_COMPLEX OR XSIMD_ENABLE_XTL_COMPLEX)
     find_package(xtl 0.8.0 REQUIRED)
     target_link_libraries(xsimd INTERFACE $<BUILD_INTERFACE:xtl>)
     target_compile_definitions(xsimd INTERFACE

docs/source/api/arch.rst

@@ -4,6 +4,7 @@
 
    The full license is in the file LICENSE, distributed with this software.
 
+.. _arch-manipulation:
 Architecture Manipulation
 =========================
 
@@ -12,13 +13,15 @@ The mentioned types are primarily used as template parameters for :ref:`batch
 <xsimd-batch-ref>`, and when interacting with :cpp:func:`xsimd::dispatch()`.
 
 The best available architecture is available at compile time through
-``xsimd::best_arch`` which also happens to be ``xsimd::default_arch``.
+``xsimd::best_arch`` which is what ``xsimd::default_arch`` defaults to unless otherwise
+configured.
 
 .. doxygengroup:: architectures
    :project: xsimd
    :members:
 
 
+.. _emulated-mode:
 Emulated Mode
 -------------
 

docs/source/api/instr_macros.rst

@@ -26,6 +26,7 @@
    }
    </style>
 
+.. _instr-set-macros:
 Instruction Set Macros
 ======================
 
@@ -35,11 +36,3 @@ can be used to filter arch-specific code.
 .. doxygengroup:: xsimd_config_macro
    :project: xsimd
    :content-only:
-
-Changing Default Architecture
-*****************************
-
-You can change the default instruction set used by xsimd (when none is provided
-explicitly) by setting the ``XSIMD_DEFAULT_ARCH`` macro to, say, ``xsimd::avx2``.
-A common usage is to set it to ``xsimd::unsupported`` as a way to detect
-instantiation of batches with the default architecture.

docs/source/api/xsimd_batch_complex.rst

@@ -17,13 +17,3 @@ Operations Specific to Batches of Complex Numbers
 .. doxygengroup:: batch_complex
    :project: xsimd
    :content-only:
-
-XTL Complex Support
--------------------
-
-If the preprocessor token ``XSIMD_ENABLE_XTL_COMPLEX`` is defined, ``xsimd``
-provides constructors of ``xsimd::batch< std::complex< T >, A >`` from
-``xtl::xcomplex``, similar to those for ``std::complex``.  This requires `XTL`_
-to be installed.
-
-.. _XTL: https://github.com/xtensor-stack/xtl

docs/source/build.rst

@@ -0,0 +1,62 @@
+.. Copyright (c) 2016, xsimd contributors
+
+   Distributed under the terms of the BSD 3-Clause License.
+
+   The full license is in the file LICENSE, distributed with this software.
+
+
+Build Options
+=============
+
+Some macros can be set to configure the behaviour of xsimd at compulte time.
+
+Changing Default Architecture
+-----------------------------
+
+You can change the default instruction set used by xsimd (when none is provided
+explicitly) by setting the ``XSIMD_DEFAULT_ARCH`` macro to, say, ``xsimd::avx2``.
+A common usage is to set it to ``xsimd::unsupported`` as a way to detect
+instantiation of batches with the default architecture.
+
+This will change the value of ``xsimd::default_arch`` used as default template parameter for
+:ref:`batch <xsimd-batch-ref>`.
+See :ref:`arch-manipulation` for all available architectures.
+
+In CMake, this can be done with the following.
+
+.. code:: cmake
+
+    target_add_compile_definitions(myproject PRIVATE XSIMD_DEFAULT_ARCH=xsimd::avx2)
+
+
+Enabling emulated architecture
+------------------------------
+
+When the compiler macro ``XSIMD_WITH_EMULATED`` is set to ``1``, xsimd also
+exhibits an emulated architecture.
+
+See :ref:`emulated-mode` for all available architectures.
+
+In CMake, this can be done with the following.
+
+.. code:: cmake
+
+    target_add_compile_definitions(myproject PRIVATE XSIMD_WITH_EMULATED=1)
+
+
+Enabling complex support with ``xtl``
+-------------------------------------
+
+If the preprocessor token ``XSIMD_ENABLE_XTL_COMPLEX`` is defined, ``xsimd``
+provides constructors of ``xsimd::batch<std::complex<T>, A>`` from
+``xtl::xcomplex``, similar to those for ``std::complex``. 
+This requires the `xtl <https://github.com/xtensor-stack/xtl>`_ library to be installed
+and in the project include directories.
+
+In CMake, this can be done with an option before the package search (xsimd 14.3 onwards).
+It will link the ``xtl`` library as well as adding the macro definition to ``xsimd`` interface.
+
+.. code:: cmake
+
+    option(XSIMD_ENABLE_XTL_COMPLEX "Enable xtl complex support" ON)
+    find_package(xsimd REQUIRED)

docs/source/build_options.rst

@@ -13,6 +13,10 @@
 
 html_theme = "sphinx_rtd_theme"
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme_options = {
+    'collapse_navigation': False,
+    'navigation_depth': 4,
+}
 
 def setup(app):
     app.add_css_file("main_stylesheet.css")

docs/source/conf.py

@@ -7,7 +7,7 @@
 .. image:: xsimd.svg
    :alt: xsimd
 
-C++ wrappers for SIMD intrinsics.
+C++14 wrappers for SIMD intrinsics.
 
 Introduction
 ------------
@@ -95,6 +95,7 @@ This software is licensed under the BSD-3-Clause license. See the LICENSE file f
    :maxdepth: 2
 
    installation
+   build_options
 
 .. toctree::
    :caption: USAGE

docs/source/index.rst

@@ -22,6 +22,9 @@
 Installation
 ============
 
+Getting the library
+-------------------
+
 `xsimd` is a header-only library, so installing it is just a matter of copying the ``include/xsimd`` directory.
 
 However we provide standardized means to install it, with package managers or with cmake.
@@ -30,46 +33,57 @@ Besides the `xsimd` headers, all these methods place the ``cmake`` project confi
 .. image:: conda.svg
 
 Using the conda-forge Package
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A package for `xsimd` is available for the `mamba <https://mamba.readthedocs.io>`_ (or `conda <https://conda.io>`_) package manager.
 
-.. code::
+.. code:: bash
 
     mamba install -c conda-forge xsimd
 
 .. image:: spack.svg
 
 Using the Spack Package
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 A package for `xsimd` is available on the `Spack <https://spack.io>`_ package manager.
 
-.. code::
+.. code:: bash
 
     spack install xsimd
     spack load xsimd
 
 .. image:: cmake.svg
 
 From Source with cmake
-----------------------
+~~~~~~~~~~~~~~~~~~~~~~
+
+You can install `xsimd` from source with `Cmake <https://cmake.org/>`_. From the source directory:
+
+.. code:: bash
+
+    cmake -B build/ -D CMAKE_INSTALL_PREFIX=/path/to/install/dir
+    cmake --build build/
+    cmake --install build/
+
+You may need to customize the default `CMake <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html>`_, for instance for picking ``nmake`` on Windows platforms:
+
+.. code:: bash
 
-You can install `xsimd` from source with `cmake <https://cmake.org/>`_. On Unix platforms, from the source directory:
+    cmake -B build/ -G "NMake Makefiles" -D CMAKE_INSTALL_PREFIX=/path/to/install/dir
+    cmake --build build/
+    cmake --install build/
 
-.. code::
 
-    mkdir build
-    cd build
-    cmake -DCMAKE_INSTALL_PREFIX=/path/to/prefix ..
-    make install
+Using the library inside CMake
+------------------------------
 
-On Windows platforms, from the source directory:
+Inside the user's ``CMakelists.txt``, the user can add xsimd to their build with the ``xsimd``
+target.
+When using CMake this way, this will set add the xsimd headers in the compiler options, as well
+as forward other xsimd requirements (minimum C++ version for instance).
 
-.. code::
+.. code:: cmake
 
-    mkdir build
-    cd build
-    cmake -G "NMake Makefiles" -DCMAKE_INSTALL_PREFIX=/path/to/prefix ..
-    nmake
-    nmake install
+    find_package(xsimd REQUIRED)
+    target_link_libraries(myproject PRIVATE xsimd)