Consolidate build options

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
-explicitely) 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