.. _dune_enable_all_packages:

dune_enable_all_packages
========================

.. cmake_function:: dune_enable_all_packages

   .. cmake_brief::

      Previously, the DUNE build system relied on the user to choose and add the compile and link flags
      necessary to build an executable. While this offers full control to the user, it
      is an error-prone procedure.

      Alternatively, users may use this function to simply add the compile flags for all
      found external modules to all executables in a DUNE module. Likewise, all found libraries are
      linked to all targets.

   .. cmake_param:: INCLUDE_DIRS
      :multi:

      A list of include directories, that should be added to all targets.
      In a standard Dune module, it is not necessary to specify anything.

   .. cmake_param:: COMPILE_DEFINITIONS
      :multi:

      A list of compile definitions, that should be added to all targets.
      In a standard Dune module, it is not necessary to specify anything.

   .. cmake_param:: COMPILE_OPTIONS
      :multi:

      A list of non-definition compile options, that should be added to all targets.
      In a standard Dune module, it is not necessary to specify anything.

   .. cmake_param:: MODULE_LIBRARIES
      :multi:

      If your module contains libraries as well as programs and if the programs should automatically
      link to those libraries, you *MUST* list these libraries in :code:`MODULE_LIBRARIES`. Those libraries will be
      automatically created by :ref:`dune_enable_all_packages` (which internally calls :ref:`dune_add_library`) and placed
      in the lib/ directory. The order of the libraries matters: if one library depends on another one, it must
      be listed after its dependency. This special handling of the libraries is due to the way newer CMake
      versions handle linking (in particular CMP022 and CMP038). You can later add source files to the library
      anywhere in the source tree by calling :ref:`dune_library_add_sources`.

      .. warning::
         The library feature requires CMake 3.1+. If you use the feature with older versions, CMake
         will emit a fatal error. Moreover, it will issue a warning if the :code:`cmake_minimum_required`
         version is older than 3.1.

   .. cmake_param:: VERBOSE
      :option:

      If this option is set, the set of compile flags, linked libraries and include directories
      that is in use for all targets in the module is printed upon configuration.

   .. cmake_param:: APPEND
      :option:

      If this option is set, the definitions, flags and directories specified in this function are
      appended to the global collection of flags instead of being prepended. Only use it, if you know
      what you are doing.

   Adds all flags and all libraries to all executables that are subsequently added in the directory
   from where this function is called and from all its subdirectories (recursively).
   If used, this function *MUST* be called in the top level CMakeLists.txt BEFORE adding any subdirectories!
   You can optionally add additional include dirs and compile definitions that will also be applied to
   all targets in the module.

   .. note::
      If you want to use :code:`dune_enable_all_packages` with an older version of CMake and your DUNE module
      creates its own library, you have to manually create the library in the top-level CMakeLists.txt
      file using :ref:`dune_add_library` (with all sources listed within that call), use
      :ref:`dune_target_enable_all_packages` to add all packages to the library and finally list that library
      under :code:`LIBRARIES` in the call to :ref:`dune_register_package_flags`. See dune-pdelab for an example of
      how to do this correctly.

   While :ref:`dune_enable_all_packages` defines the user interface for this feature, developers might
   also be interested in the following related functions:

   * :ref:`dune_target_enable_all_packages`
   * :ref:`dune_register_package_flags`
   * :ref:`dune_library_add_sources`

