..
   This file is part of Logtalk <https://logtalk.org/>  
   Copyright 1998-2019 Paulo Moura <pmoura@logtalk.org>

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.


.. index:: logtalk_make/1
.. _predicates_logtalk_make_1:

logtalk_make/1
==============

Description
-----------

::

   logtalk_make(Target)

Runs a make target. Fails of the target is not valid.

Allows reloading all Logtalk source files that have been modified since
last loaded when called with the target ``all``, deleting all
intermediate files generated by the compilation of Logtalk source files
when called with the target ``clean``, checking for code issues when
called with the target ``check``, listing of circular dependencies
between pairs or trios of objects when called with the target
``circular``, generating documentation when called with the target
``documentation``, and deleting the :term:`dynamic binding` caches with
the target ``caches``.

There are also three variants of the ``all`` target: ``debug``,
``normal``, and ``optimal``. These targets change the compilation mode
(by changing the default value of the :ref:`debug <flag_debug>` and
:ref:`optimize <flag_optimize>` flags) and reload all affected files 
(i.e. all files loaded without an explicit ``debug/1`` or ``optimize/1``
compiler option).

When using the ``all`` target, only source files loaded using the
:ref:`predicates_logtalk_load_1` and :ref:`predicates_logtalk_load_2`
predicates are reloaded. Non-modified files will also be reloaded when
there is a change to the compilation mode (i.e. when the files were loaded
without explicit :ref:`debug <flag_debug>` or :ref:`optimize <flag_optimize>`
flags and the default values of these flags changed after loading; no check
is made, however, for other implicit compiler flags that may have changed
since loading). When an included file is modified, this target reloads its
main file (i.e. the file that contains the :ref:`directives_include_1`
directive).

When using the ``check`` or ``circular`` targets, be sure to compile
your source files with the :ref:`source_data <flag_source_data>` flag
turned on for complete and detailed reports.

When using the ``check`` target, predicates for messages sent to objects
that implement the :ref:`forwarding <apis:forwarding/0>` built-in protocol
are not reported. While this usually avoids only false positives, it may
also result in failure to report true missing predicates in some cases.

When using the ``circular`` target, be prepared for a lengthy
computation time for applications with a large combined number of
objects and message calls. Only mutual and triangular dependencies are
checked due to the computational cost.

The ``documentation`` target requires the ``doclet`` tool and a single
*doclet* object to be loaded. See the ``doclet`` tool for more details.

Depending on the :term:`backend Prolog compiler`, the following top-level
shortcuts are usually defined:

* ``{*}`` - ``logtalk_make(all)``
* ``{!}`` - ``logtalk_make(clean)``
* ``{?}`` - ``logtalk_make(check)``
* ``{@}`` - ``logtalk_make(circular)``
* ``{#}`` - ``logtalk_make(documentation)``
* ``{$}`` - ``logtalk_make(caches)``
* ``{+d}`` - ``logtalk_make(debug)``
* ``{+n}`` - ``logtalk_make(normal)``
* ``{+o}`` - ``logtalk_make(optimal)``

Check the :term:`adapter files <adapter file>` for the availability of
these shortcuts as they are not part of the language.

.. warning::

   Only use the shortcuts at the top-level interpreter and
   never in source files.

The target actions can be extended by defining clauses for the multifile
and dynamic hook predicate ``logtalk_make_target_action(Target)`` where
``Target`` is one of the targets listed above. The additional user
defined actions are run after the default ones.

Modes and number of proofs
--------------------------

::

   logtalk_make(+atom) - zero_or_one

Errors
------

(none)

Examples
--------

::

   % reload loaded source files in debug mode:
   | ?- logtalk_make(debug).

   % check for code issues in the loaded source files:
   | ?- logtalk_make(check).

   % delete all intermediate files generated by
   % the compilation of Logtalk source files:
   | ?- logtalk_make(clean).

.. seealso::

   :ref:`predicates_logtalk_compile_1`,
   :ref:`predicates_logtalk_compile_2`,
   :ref:`predicates_logtalk_load_1`,
   :ref:`predicates_logtalk_load_2`,
   :ref:`predicates_logtalk_make_0`,
   :ref:`predicates_logtalk_make_target_action_1`
