Build Automation for Ciao
*************************

'ciao_builder' is a build automation
(https://en.wikipedia.org/wiki/Build_automation) system for managing
Ciao libraries and programs.  'ciao_builder' works on structured
collections of code, dubbed as bundles.

Indexes

Introduction
************

The Ciao builder manages collections of source code, implementing the
automatic configuration, build, (un)installation, packing, and cleaning
of collections of Ciao modules.  It offers a simplified interface with
other Ciao (compiler, documentation generator, etc.)  and external tools
(e.g., installation of third-party software for library bindings).

This tool also offers all the necessary machinery to bootstrap the Ciao
system from a reduced set of dependencies.

See the Ciao reference manual for a description of bundles, workspaces,
and the basic usage of the builder tool.

The standalone command-line builder
***********************************

Author(s): Jose F. Morales, The Ciao Development Team.

'ciao_builder' is the Ciao standalone command-line builder.
'ciao_builder' can be used to manage Ciao source code organized as
bundles.

This command is available to the user in two forms: wrapped around the
'ciao-boot.sh' (or 'ciao-boot.bat' in Windows) scripts (see
Bootstrapping the build system), or as part of the general 'ciao'
command-line tool.

Introduction to the build process
=================================

This picture shows a detailed view all the elements of the build and
installation process of a bundle or collection of bundles.

         Phase 0-
            Bootstrapping the build system
         Phase 1-
            SOURCE ---(configure)--> CONFIG
         Phase 2- (needs CONFIG)
            SOURCE ---(build)--> BUILD --(install)--> INSTALLED

Above, arrows specify actions and nodes are collections of files:

SOURCE
     Source code
CONFIG
     Configuration of the source
BUILD
     Binaries, compiled libraries, and generated documentation (.pdf,
     .html, etc.)
INSTALLED
     Copies of BUILD that exclude temporary files (mostly caches for
     separate and incremental compilation).

The source distribution only contains SOURCE elements.  The actions
'build' and 'install' create the BUILD and INSTALLED elements.

NOTE: Bootstrapping is a transparent process and its details are not
needed to understand and use the build system.  See Bootstrapping the build system
for more details on phase 0.

NOTE: Out-of-tree builds (where all the intermediate compiler output,
including '.po'/'.itf' files are stored in the 'build/cache' directory)
are enabled by default for bundles.  This can be disabled setting the
environment variable 'CIAOCCACHE=0'.  Note that bootstrapping the system
with 'CIAOCCACHE=0' is not recommended, as it will merge '.po'/'.itf'
files of (potentially) incompatible compiler iterations.

Configuration and build
=======================

Configuration and build can be reverted with clean commands.  The
meaning of 'clean' and 'distclean' is based on their standard meaning
(see the 'Makefile' example at
<http://www.gnu.org/software/make/manual/html_node/Complex-Makefile.html>),
except for 'realclean' that cleans both the system and the bootstrap
(equivalent to 'distclean' and 'boot-clean').

The following table summarizes the actions that undo each build or
install operation:

         ('undo' reverts the effect of each marked 'action')
                       ,--------+-----------+-----------.
        actions \ undo | clean  | distclean | realclean |
      .----------------+--------+-----------+-----------+
      | boot-build     |        |           |    x      |
      +----------------+--------+-----------+-----------+
      | configure      |        |     x     |    x      |
      +----------------+--------+-----------+-----------+
      | build          |   x    |     x     |    x      |
      `----------------+--------+-----------+-----------+

Installation
============

Different installation areas are supported.  For personal installations,
the installation area can overlap with the build staging area, such that
no extra space is necessary.

           .............         install             ...........
           .           .---------------------------->.         .
           .           .        (generated           .         .
           .............         files such          ...........
            Build Staging Area       as binaries)      Installation Area
                .^.                                 _
                 | build                            /|
                 |                                 /
           .............          install         /
           .           .-------------------------'
           .           .         (source files
           .............          such as examples,
            Source Code           images, etc.)

The 'install' command is undone with the 'uninstall' command.

Bootstrapping the build system
==============================

The 'ciao-boot.sh' (or 'ciao-boot.bat' in Windows) command automatically
bootstraps and invokes the Ciao build system.  The process is described
below.

Bootstrapping is the process that compiles the Ciao compiler and builder
in an environment where no existing Ciao binary exists.  We follow the
same phase 1 and phase 2 steps above but the whole process is driven by
a very simplified version written in (portable) shell-script code (since
there is no running Ciao) and using the 'ciaoc' bootstrap compiler.

The 'ciaoc' bootstrap compiler comes in a pre-compiled bytecode form.
This bytecode, together with the engine parts written in C, can be
executed in most systems with a C compiler.

Once this bootstrap compiler is available, the system compiles the
bootstrap 'ciao_builder', which drives the rest of the build and
installation process.

This step is transparent to the user and separated in a different build
directory ('build-boot/').  However, there are options to force the
recompilation and cleaning of that part (see 'ciao-boot.sh' help for
more information).

Ciao command-line parser
************************

Author(s): Jose F. Morales, The Ciao Development Team.

Parser of builder commands (based on a generic command line parser).

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(ciaocl_parser)).'
   * Exports:

        - Predicates:

          'parse_cmd/3', 'norm_underscores/2'.

Documentation on exports
========================

 -- PREDICATE: parse_cmd/3:
     No further documentation available for this predicate.

 -- PREDICATE: norm_underscores/2:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - System library modules:

     'lists', 'hiordlib'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'isomodes', 'regtypes', 'dcg'.

Ciao command-line Help
**********************

Author(s): The Ciao Development Team, Jose F. Morales.

Formatted help for the 'ciao' and 'ciao-boot.sh' ( 'ciao-boot.bat')
command line tool

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(ciaocl_help)).'
   * Exports:

        - Predicates:

          'show_help/2', 'show_help_cmd/2'.

Documentation on exports
========================

 -- PREDICATE: show_help/2:

     Usage: 'show_help(Level,Prof)'

     Show help for the command line interface.  'Level' specifies the
     detail level and 'Prof' the command line profile (useful when the
     same command may act in different ways).
        - Call and exit should be compatible with:

          'ciaocl_help:help_level(Level)' ('ciaocl_help:help_level/1')

          'Prof' is an atom.  ('basic_props:atm/1')
        - The following properties should hold at call time:

          'Level' is currently a term which is not a free variable.
          ('term_typing:nonvar/1')

          'Prof' is currently a term which is not a free variable.
          ('term_typing:nonvar/1')

 -- PREDICATE: show_help_cmd/2:

     Usage: 'show_help_cmd(Cmd,Prof)'

     Show detailed help on the specified command 'Cmd' (shows help of
     the command group)

Documentation on imports
========================

This module has the following direct dependencies:
   - System library modules:

     'datafacts_rt', 'aggregates', 'lists', 'stream_utils', 'system'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'isomodes', 'regtypes', 'dcg',
     'fsyntax', 'datafacts'.

Manifest compiler
*****************

Author(s): Jose F. Morales.

This module implements predicates to load, consult, and compile
'Manifest.pl' files.  A Manifest file allows the specification of a
bundle:

   * dependencies to other bundles
   * configuration flags (see 'bundle_configure')
   * primitive targets (see 'grade_bin', 'grade_docs', etc.)
   * nested definitions for bundle parts
   * custom definitions for build commands (see 'builder_cmds')

NOTE: Configuration flags and nested definitions must be defined in a
'<bundle>.hooks.pl' module.

Use 'make_bundlereg/4' for processing of 'Manifest.pl' files into bundle
registry entries.  Bundle registries are written using 'fastrw' so that
the support code to load them is minimal.  They include cheaper runtime
meta-information (like dependencies, versions, path aliases, etc.).

For registered bundles, you can use 'ensure_load_manifest/1' and
'manifest_call/2' for loading and consulting a bundle specification.

NOTE: Users should never call custom build command definitions directly
with 'manifest_call/2'.  Use 'builder_cmds' instead.

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(manifest_compiler)).'
   * Exports:

        - Predicates:

          'is_bundledir/1', 'locate_manifest_file/2',
          'lookup_bundle_root/2', 'ensure_load_manifest/1',
          'manifest_call/2', 'manifest_current_predicate/2',
          'split_target/3', 'compose_target/3', 'target_is_bundle/1',
          'make_bundlereg/4', 'bundle_info/1', 'get_bundle_readme/2',
          'bundle_manual_base/2', 'main_file_relpath/2',
          'main_file_path/3'.
        - Multifiles:

          'm_bundlehook_decl/3', 'm_bundlehook_do/3',
          'm_third_party_name/1', 'm_third_party_version/2',
          'm_third_party_source_url/2', 'm_third_party_source_md5/2',
          'm_third_party_patch/2', 'm_third_party_build_system/2',
          'm_third_party_option1/2', 'm_third_party_option2/3',
          'm_third_party_custom_configure/2',
          'm_third_party_custom_build/2',
          'm_third_party_custom_install/2', 'm_bundle_config_call/2',
          'm_bundle_config_entry/3', 'm_bundle_foreign_config_tool/3',
          'm_bundle_foreign_dep/4'.

Documentation on exports
========================

 -- PREDICATE: is_bundledir/1:

     Usage: 'is_bundledir(BundleDir)'

     'BundleDir' is the directory for a bundle (i.e., contains a
     Manifest.pl file

 -- PREDICATE: locate_manifest_file/2:

     Usage: 'locate_manifest_file(BundleDir,ManifestFile)'

     Given 'BundleDir' a bundle directory, 'ManifestFile' is unified
     with the name of the manifest file

 -- PREDICATE: lookup_bundle_root/2:

     Usage: 'lookup_bundle_root(File,BundleDir)'

     Detect the bundle root dir for the given File (a directory or
     normal file)

 -- PREDICATE: ensure_load_manifest/1:

     Usage: 'ensure_load_manifest(Target)'

     Ensure that the manifest for 'Target' is loaded (including Manifest
     sentences and .hooks.pl modules).  The bundle must have been
     scanned before, so that its source directory is known.

 -- PREDICATE: manifest_call/2:

     Usage: 'manifest_call(Target,Head)'

     Call 'Target:Head', a predicate defined in a Manifest (fact,
     predicate in hooks, or nested predicate)

 -- PREDICATE: manifest_current_predicate/2:

     Usage: 'manifest_current_predicate(Target,Head)'

     'Head' is declared in 'Target'

 -- PREDICATE: split_target/3:
     No further documentation available for this predicate.

 -- PREDICATE: compose_target/3:
     No further documentation available for this predicate.

 -- PREDICATE: target_is_bundle/1:
     No further documentation available for this predicate.

 -- PREDICATE: make_bundlereg/4:

     Usage: 'make_bundlereg(Bundle,BundleDir,FinalBundleDir,RegFile)'

     Generate a bundlereg 'RegFile' for bundle 'Bundle' at 'BundleDir',
     where the final bundle directory is 'FinalBundleDir'.

 -- PREDICATE: bundle_info/1:

     Usage: 'bundle_info(Bundle)'

     Show info of 'Bundle'

 -- PREDICATE: get_bundle_readme/2:
     No further documentation available for this predicate.

 -- PREDICATE: bundle_manual_base/2:
     No further documentation available for this predicate.

 -- PREDICATE: main_file_relpath/2:
     No further documentation available for this predicate.

 -- PREDICATE: main_file_path/3:
     No further documentation available for this predicate.

Documentation on multifiles
===========================

 -- PREDICATE: m_bundlehook_decl/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundlehook_do/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_name/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_version/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_source_url/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_source_md5/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_patch/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_build_system/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_option1/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_option2/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_custom_configure/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_custom_build/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_custom_install/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_config_call/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_config_entry/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_foreign_config_tool/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_foreign_dep/4:
     No further documentation available for this predicate.  The
     predicate is multifile.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'bundlehooks_holder', 'builder_aux', 'bundle_fetch'.
   - System library modules:

     'datafacts_rt', 'messages', 'pathnames', 'system', 'port_reify',
     'bundle_paths', 'read', 'aggregates', 'system_extra',
     'version_strings', 'lists', 'terms', 'fastrw', 'stream_utils',
     'bundle_info', 'format'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'fsyntax', 'hiord', 'assertions',
     'assertions/assertions_basic', 'regtypes', 'isomodes', 'datafacts'.

bundlehooks_holder (library)
****************************

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(bundlehooks_holder)).'
   * Exports:

        - Predicates:

          'do_use_module/1', 'do_unload/1'.

Documentation on exports
========================

 -- PREDICATE: do_use_module/1:
     No further documentation available for this predicate.

 -- PREDICATE: do_unload/1:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - System library modules:

     'compiler'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'dynmod_holder'.

Builder commands
****************

Author(s): Jose F. Morales.

This module contains a high-level interface to the builder (
'builder_run/2') and other predicates to interact to the build process
from '.hooks.pl' files ( 'builder_cmd/2', etc.).

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(builder_cmds)).'
   * Exports:

        - Predicates:

          'builder_run/2', 'builder_cmd_nobndl/1', 'list_bundles/0',
          'builder_cleanup/0', 'builder_cmd_on_set/2', 'builder_cmd/2',
          'root_target/1', 'target_is_workspace/1',
          'bundle_share_workspace/2'.
        - Multifiles:

          'cmd.comment/2', 'cmd.grade/2', 'cmd.only_global_instype/1',
          'cmd.needs_update_builder/1', 'cmd.needs_rescan/1',
          'cmd.needs_config/1', 'cmd.allow_unknown_targets/1',
          'cmd.no_manifest_load/1', 'cmd.recursive/2',
          'cmd.do_before.decl/1', 'cmd.do_before/2', 'cmd.do.decl/1',
          'cmd.do/2', 'cmd.do_after.decl/1', 'cmd.do_after/2',
          'grade.cmd/3', 'grade.requires/3', 'grade.prim_do/4',
          'grade.prim_kind/2', 'gen_pbundle_hook/3'.

Documentation on exports
========================

 -- PREDICATE: builder_run/2:
     No further documentation available for this predicate.

 -- PREDICATE: builder_cmd_nobndl/1:
     No further documentation available for this predicate.

 -- PREDICATE: list_bundles/0:

     Usage:

     List all registered bundles

 -- PREDICATE: builder_cleanup/0:

     Usage:

     Cleanup the builder state

 -- PREDICATE: builder_cmd_on_set/2:
     No further documentation available for this predicate.

 -- PREDICATE: builder_cmd/2:

     Usage: 'builder_cmd(Cmd,Target)'

     Perform command 'Cmd' on target 'Target'

 -- PREDICATE: root_target/1:

     Usage:

     Target for the whole CIAOROOT workspace.

 -- PREDICATE: target_is_workspace/1:
     No further documentation available for this predicate.

 -- PREDICATE: bundle_share_workspace/2:
     No further documentation available for this predicate.

Documentation on multifiles
===========================

 -- PREDICATE: cmd.comment/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.grade/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.only_global_instype/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.needs_update_builder/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.needs_rescan/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.needs_config/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.allow_unknown_targets/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.no_manifest_load/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.recursive/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_before.decl/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_before/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do.decl/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_after.decl/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_after/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.cmd/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.requires/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.prim_do/4:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.prim_kind/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: gen_pbundle_hook/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'builder_targets', 'bundle_fetch', 'builder_flags',
     'bundle_configure', 'ciaoc_aux', 'messages_aux', 'install_aux',
     'manifest_compiler', 'grade_holder', 'grade_bin', 'grade_docs',
     'grade_analyze', 'config_common', 'interactive_aux', 'builder_aux',
     'third_party_install', 'pbundle_generator', 'pbundle_gen_win32',
     'pbundle_gen_rpm', 'pbundle_gen_mac', 'pbundle_gen_src',
     'pbundle_gen_bin', 'bundle_hash', 'lpdoc_aux'.
   - System library modules:

     'datafacts_rt', 'format', 'sort', 'aggregates', 'lists',
     'pathnames', 'bundle_paths'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'fsyntax', 'hiord', 'assertions',
     'assertions/assertions_basic', 'regtypes', 'isomodes', 'datafacts'.

Binary grade
************

Author(s): Jose F. Morales.

This module contains command definitions for the 'bin' grade, which
builds/clean/install/uninstall binaries from sources.

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(grade_bin)).'

Documentation on multifiles
===========================

 -- PREDICATE: cmd.comment/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.grade/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.only_global_instype/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.needs_update_builder/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.needs_rescan/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.needs_config/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.allow_unknown_targets/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.no_manifest_load/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.recursive/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_before.decl/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_before/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do.decl/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_after.decl/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_after/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.cmd/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.requires/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.prim_do/4:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.prim_kind/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'builder_cmds', 'manifest_compiler', 'builder_aux', 'ciaoc_aux',
     'install_aux', 'messages_aux', 'car_maker'.
   - System library modules:

     'bundle_paths', 'pathnames', 'lists'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'fsyntax', 'hiord', 'assertions',
     'assertions/assertions_basic', 'regtypes', 'isomodes'.

Docs grade
**********

Author(s): Jose F. Morales.

This module contains command definitions for the 'docs' grade, which
builds/clean/install/uninstall documentation from sources.

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(grade_docs)).'

Documentation on multifiles
===========================

 -- PREDICATE: cmd.comment/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.grade/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.only_global_instype/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.needs_update_builder/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.needs_rescan/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.needs_config/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.allow_unknown_targets/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.no_manifest_load/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.recursive/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_before.decl/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_before/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do.decl/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_after.decl/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: cmd.do_after/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.cmd/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.requires/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.prim_do/4:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: grade.prim_kind/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'builder_cmds', 'manifest_compiler', 'builder_aux',
     'config_common', 'lpdoc_aux', 'install_aux', 'messages_aux'.
   - System library modules:

     'terms', 'bundle_info'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'fsyntax', 'hiord', 'assertions',
     'assertions/assertions_basic', 'regtypes', 'isomodes'.

Targets for builder
*******************

Author(s): Jose F. Morales.

This module defines predicates to map between input targets (which can
be paths to bundles, bundle names, or paths to workspaces) and resolved
target names (absolute paths to workspace or symbolic bundle names)

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(builder_targets)).'
   * Exports:

        - Predicates:

          'rescan_targets/1', 'resolve_targets/3'.

Documentation on exports
========================

 -- PREDICATE: rescan_targets/1:

     Usage: 'rescan_targets(Targets)'

     (Re)scan bundles at the workspaces where targets are located
        - Call and exit should be compatible with:

          'Targets' is a list of 'atm's.  ('basic_props:list/2')
        - The following properties should hold at call time:

          'Targets' is currently a term which is not a free variable.
          ('term_typing:nonvar/1')

 -- PREDICATE: resolve_targets/3:

     Usage: 'resolve_targets(Targets0,OnUnknown,Targets)'

     Resolve targets (which may be paths).  This assumes that
     'rescan_targets/1' has been called
        - Call and exit should be compatible with:

          'Targets0' is a list of 'atm's.  ('basic_props:list/2')

          'OnUnknown' is any term.  ('basic_props:term/1')

          'Targets' is a list of 'target's.  ('basic_props:list/2')
        - The following properties should hold at call time:

          'Targets0' is currently a term which is not a free variable.
          ('term_typing:nonvar/1')

          'Targets' is a free variable.  ('term_typing:var/1')

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'bundle_scan', 'builder_aux', 'manifest_compiler', 'bundle_fetch'.
   - System library modules:

     'datafacts_rt', 'hiordlib', 'system'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'fsyntax', 'hiord', 'assertions',
     'assertions/assertions_basic', 'regtypes', 'isomodes', 'datafacts'.

Installation of third-party components
**************************************

Author(s): Remy Haemmerle, Jose F. Morales.

This module implements automatic fetch and build and installation of
third-party components, without interfering with the system installed
software.

It works similarly to package managers like GNU stow
(https://www.gnu.org/software/stow/), Homebrew (http://brew.sh/), or GNU
Guix (https://www.gnu.org/software/guix/manual/guix.html), where each
package is installed separately in its own directory and symbolic links
are created to common 'bin/', 'lib/', etc.  directories.

The supported build systems are:

'gnu_build_system'
     See
     <http://www.gnu.org/prep/standards/standards.html#Configuration>

Specification of third-party components
=======================================

TODO: Document this feature

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(third_party_install)).'
   * Exports:

        - Predicates:

          'third_party_path/2', 'clean/1', 'download/1',
          'decompress_and_patch/2', 'checksum/1', 'configure/1',
          'build/1', 'installed/1', 'install/1', 'activated/1',
          'activate/1', 'deactivate/1', 'uninstall/1', 'auto_install/2'.
        - Multifiles:

          'm_bundlehook_decl/3', 'm_bundlehook_do/3',
          'm_third_party_name/1', 'm_third_party_version/2',
          'm_third_party_source_url/2', 'm_third_party_source_md5/2',
          'm_third_party_patch/2', 'm_third_party_build_system/2',
          'm_third_party_option1/2', 'm_third_party_option2/3',
          'm_third_party_custom_configure/2',
          'm_third_party_custom_build/2',
          'm_third_party_custom_install/2', 'm_bundle_config_call/2',
          'm_bundle_config_entry/3', 'm_bundle_foreign_config_tool/3',
          'm_bundle_foreign_dep/4'.

Documentation on exports
========================

 -- PREDICATE: third_party_path/2:
     No further documentation available for this predicate.

 -- PREDICATE: clean/1:
     No further documentation available for this predicate.

 -- PREDICATE: download/1:
     No further documentation available for this predicate.

 -- PREDICATE: decompress_and_patch/2:
     No further documentation available for this predicate.

 -- PREDICATE: checksum/1:
     No further documentation available for this predicate.

 -- PREDICATE: configure/1:
     No further documentation available for this predicate.

 -- PREDICATE: build/1:
     No further documentation available for this predicate.

 -- PREDICATE: installed/1:
     No further documentation available for this predicate.

 -- PREDICATE: install/1:
     No further documentation available for this predicate.

 -- PREDICATE: activated/1:
     No further documentation available for this predicate.

 -- PREDICATE: activate/1:
     No further documentation available for this predicate.

 -- PREDICATE: deactivate/1:
     No further documentation available for this predicate.

 -- PREDICATE: uninstall/1:
     No further documentation available for this predicate.

 -- PREDICATE: auto_install/2:
     No further documentation available for this predicate.

Documentation on multifiles
===========================

 -- PREDICATE: m_bundlehook_decl/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundlehook_do/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_name/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_version/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_source_url/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_source_md5/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_patch/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_build_system/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_option1/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_option2/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_custom_configure/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_custom_build/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_custom_install/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_config_call/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_config_entry/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_foreign_config_tool/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_foreign_dep/4:
     No further documentation available for this predicate.  The
     predicate is multifile.

Documentation on imports
========================

This module has the following direct dependencies:
   - System library modules:

     'aggregates', 'terms', 'lists', 'bundle_paths', 'http_get',
     'md5sum', 'pathnames', 'process', 'system'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic'.

Installation of custom third-party components
*********************************************

Author(s): The Ciao Development Team.

This module implements installation of third-party components using
custom installers (e.g., manual, 'npm', etc.)

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(third_party_custom)).'
   * Exports:

        - Predicates:

          'third_party_custom_install/1', 'third_party_custom_path/2'.
        - Multifiles:

          'm_bundle_foreign_dep/4'.

Documentation on exports
========================

 -- PREDICATE: third_party_custom_install/1:
     No further documentation available for this predicate.

 -- PREDICATE: third_party_custom_path/2:
     No further documentation available for this predicate.

Documentation on multifiles
===========================

 -- PREDICATE: m_bundle_foreign_dep/4:
     No further documentation available for this predicate.  The
     predicate is multifile.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'messages_aux', 'third_party_install'.
   - System library modules:

     'aggregates', 'format', 'pathnames', 'system_extra', 'system',
     'process', 'port_reify'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'basicmodes', 'fsyntax', 'hiord'.

Build code using the Ciao compiler
**********************************

Author(s): Jose F. Morales, The Ciao Development Team.

This is a wrapper around 'ciaoc' (and other Ciao tools) that extends the
functionality of the Ciao compiler:

   * Invoke the compiler as a external processes
   * Batch compilation of collection of modules
   * Emulator generation and compilation

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(ciaoc_aux)).'
   * Exports:

        - Predicates:

          'invoke_boot_ciaoc/2', 'invoke_ciaoc/1',
          'invoke_ciaosh_batch/1', 'invoke_ciaosh_batch/2',
          'promote_bootstrap/1', 'build_eng_exec_header/1',
          'clean_eng_exec_header/1', 'create_windows_bat/6',
          'cmd_build/1', 'cmd_build_copy/4', 'cmd_build_link/4',
          'build_libs/2', 'runtests_dir/2', 'runtests_dir/3',
          'exists_and_compilable/1', 'clean_tree/1',
          'cachedir_prefix/2', 'clean_mods/1'.

Documentation on exports
========================

 -- PREDICATE: invoke_boot_ciaoc/2:
     No further documentation available for this predicate.

 -- PREDICATE: invoke_ciaoc/1:
     No further documentation available for this predicate.

 -- PREDICATE: invoke_ciaosh_batch/1:
     No further documentation available for this predicate.

 -- PREDICATE: invoke_ciaosh_batch/2:
     No further documentation available for this predicate.

 -- PREDICATE: promote_bootstrap/1:

     Usage: 'promote_bootstrap(Eng)'

     Promote the current 'ciaoc' and products of 'emugen' as the next
     bootstrap compiler ('ciaoc.sta' and absmach code)

 -- PREDICATE: build_eng_exec_header/1:
     No further documentation available for this predicate.

 -- PREDICATE: clean_eng_exec_header/1:
     No further documentation available for this predicate.

 -- PREDICATE: create_windows_bat/6:
     No further documentation available for this predicate.

 -- PREDICATE: cmd_build/1:
     No further documentation available for this predicate.

 -- PREDICATE: cmd_build_copy/4:
     No further documentation available for this predicate.

 -- PREDICATE: cmd_build_link/4:
     No further documentation available for this predicate.

 -- PREDICATE: build_libs/2:
     No further documentation available for this predicate.

 -- PREDICATE: runtests_dir/2:
     No further documentation available for this predicate.

 -- PREDICATE: runtests_dir/3:
     No further documentation available for this predicate.

 -- PREDICATE: exists_and_compilable/1:
     No further documentation available for this predicate.

 -- PREDICATE: clean_tree/1:
     No further documentation available for this predicate.

 -- PREDICATE: cachedir_prefix/2:
     No further documentation available for this predicate.

 -- PREDICATE: clean_mods/1:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'messages_aux', 'builder_aux', 'config_common', 'cpx_process',
     'bundle_configure', 'eng_defs', 'install_aux'.
   - System library modules:

     'lists', 'aggregates', 'system_extra', 'pathnames', 'bundle_paths',
     'messages', 'system', 'terms', 'stream_utils', 'source_tree',
     'sort', 'bundle_flags', 'process', 'sh_process'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'fsyntax', 'hiord', 'dcg'.

Build documentation using LPdoc
*******************************

Author(s): Jose F. Morales, The Ciao Development Team.

This is a wrapper around 'lpdoc' to build the documentation of a bundle.
It uses 'lpdoc' as an external process so that no hard dependencies are
introduced.

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(lpdoc_aux)).'
   * Exports:

        - Predicates:

          'invoke_lpdoc/1', 'build_docs_readme/3',
          'build_docs_readme_html/3', 'build_doc/2', 'show_doc/3',
          'bld_manual_path/4', 'inst_manual_path/4',
          'act_manual_path/4'.

Documentation on exports
========================

 -- PREDICATE: invoke_lpdoc/1:
     No further documentation available for this predicate.

 -- PREDICATE: build_docs_readme/3:
     No further documentation available for this predicate.

 -- PREDICATE: build_docs_readme_html/3:
     No further documentation available for this predicate.

 -- PREDICATE: build_doc/2:
     No further documentation available for this predicate.

 -- PREDICATE: show_doc/3:
     No further documentation available for this predicate.

 -- PREDICATE: bld_manual_path/4:
     No further documentation available for this predicate.

 -- PREDICATE: inst_manual_path/4:
     No further documentation available for this predicate.

 -- PREDICATE: act_manual_path/4:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'config_common', 'cpx_process', 'builder_aux', 'install_aux'.
   - System library modules:

     'system', 'source_tree', 'pathnames', 'bundle_paths'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'fsyntax', 'hiord', 'assertions',
     'assertions/assertions_basic', 'regtypes', 'isomodes'.

.car file maker
***************

Author(s): Jose F. Morales, The Ciao Development Team.

This module implements a minimalistic build system for the engine, which
includes an incremental build system for C code, some of them
automatically generated from 'emugen'.  The output can be both native
executables, dynamic, and/or static libraries.

See 'eng_defs' and 'build_car.sh' for more details.

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(car_maker)).'
   * Exports:

        - Predicates:

          'eng_build/1', 'eng_clean/1', 'bundle_flags_sh_file/1',
          'sysconf_os/1', 'sysconf_arch/3'.

Documentation on exports
========================

 -- PREDICATE: eng_build/1:
     No further documentation available for this predicate.

 -- PREDICATE: eng_clean/1:
     No further documentation available for this predicate.

 -- PREDICATE: bundle_flags_sh_file/1:
     No further documentation available for this predicate.

 -- PREDICATE: sysconf_os/1:
     No further documentation available for this predicate.

 -- PREDICATE: sysconf_arch/3:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'messages_aux', 'ciaoc_aux', 'eng_defs', 'bundle_hash',
     'builder_aux'.
   - System library modules:

     'lists', 'terms', 'system', 'system_extra', 'pathnames',
     'bundle_paths', 'sh_process', 'bundle_info', 'version_strings'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'fsyntax', 'hiord', 'dcg'.

Engine maker: defs and paths
****************************

Author(s): Jose F. Morales, The Ciao Development Team.

This module defines engine specifications for builds.  Engines are
defined using the 'emugen' package.  Engine build specifications
contains parameters that affects the compiled engine:

Engine options:
   * 'cross(OS,Arch)': force cross compilation to selected platform
   * 'boot': the boot engine
   * 'addpath(Spec)': additional (symbolic) source path for locating C
     and header files (handy for custom engines)
   * 'h_alias(Alias)': subdirectory for headers (i.e., name used to
     include header for this engine '#include <ciao/...>')

Engine build directory layout
=============================

Sections at the engine build directory layout:
       hdir: C headers
       cdir: C source files
       cfgdir: sysdep config files
       objdir: sysdep compiled object files
       engdir: root directory for engine build
       exec: engine as an executable
       lib_so: engine as a C shared library
       lib_a: engine as a C static library
     (for engine activation)
       objdir_anyarch: compiled object files root
       exec_anyarch: engine as an executable -- link to active architecture

NOTE: This hierarchy is assumed by other tools and code like
'build_car.sh'.  Please be careful if introducing any change.

Example: directory hierarchy at 'build/eng/ciaoengine/':
     cfg
     cfg/DARWINx86_64
     cfg/DARWINx86_64/config_mk
     cfg/DARWINx86_64/config_sh
     cfg/DARWINx86_64/meta_sh
     include
     include/ciao
     include/ciao/*.h
     include/*.h
     objs
     objs/ciaoengine
     objs/ciaoengine.DARWINx86_64
     objs/DARWINx86_64
     objs/DARWINx86_64/*.o
     objs/DARWINx86_64/*.P
     src
     src/*.c

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(eng_defs)).'
   * Exports:

        - Predicates:

          'eng_cfg/2', 'eng_mainspec/2', 'eng_opts/2', 'eng_bundle/2',
          'eng_mainmod/2', 'eng_mainbase/2', 'eng_srcdirs/2',
          'emugen_code_dir/3', 'eng_h_alias/2', 'eng_path/3',
          'inst_eng_path/3', 'active_bld_eng_path/3',
          'active_inst_eng_path/3', 'active_eng_name/3',
          'bld_cmake_path/3'.

Documentation on exports
========================

 -- PREDICATE: eng_cfg/2:
     No further documentation available for this predicate.

 -- PREDICATE: eng_mainspec/2:
     No further documentation available for this predicate.

 -- PREDICATE: eng_opts/2:
     No further documentation available for this predicate.

 -- PREDICATE: eng_bundle/2:
     No further documentation available for this predicate.

 -- PREDICATE: eng_mainmod/2:
     No further documentation available for this predicate.

 -- PREDICATE: eng_mainbase/2:
     No further documentation available for this predicate.

 -- PREDICATE: eng_srcdirs/2:
     No further documentation available for this predicate.

 -- PREDICATE: emugen_code_dir/3:
     No further documentation available for this predicate.

 -- PREDICATE: eng_h_alias/2:
     No further documentation available for this predicate.

 -- PREDICATE: eng_path/3:
     No further documentation available for this predicate.

 -- PREDICATE: inst_eng_path/3:
     No further documentation available for this predicate.

 -- PREDICATE: active_bld_eng_path/3:
     No further documentation available for this predicate.

 -- PREDICATE: active_inst_eng_path/3:
     No further documentation available for this predicate.

 -- PREDICATE: active_eng_name/3:
     No further documentation available for this predicate.

 -- PREDICATE: bld_cmake_path/3:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'config_common', 'install_aux'.
   - System library modules:

     'lists', 'aggregates', 'terms', 'pathnames', 'bundle_paths',
     'bundle_flags'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'fsyntax'.

Auxiliary Predicates for Builder
********************************

Author(s): The Ciao Development Team.

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(builder_aux)).'
   * Exports:

        - Predicates:

          'dir_to_bundle/2', 'lookup_workspace/3', 'invoke_gmake/2',
          'invoke_ant/2', 'ensure_builddir/2', 'builddir_clean/2',
          'wr_template/4', 'generate_version_auto/2',
          'generate_config_auto/2', 'print_clauses_to_file/2',
          'update_file_from_clauses/3', 'update_file_from_string/3',
          'add_rpath/3', 'third_party_aux/3', 'update_stat_config_sh/2',
          'remove_dir_nofail/1'.

Documentation on exports
========================

 -- PREDICATE: dir_to_bundle/2:
     No further documentation available for this predicate.

 -- PREDICATE: lookup_workspace/3:
     No further documentation available for this predicate.

 -- PREDICATE: invoke_gmake/2:
     No further documentation available for this predicate.

 -- PREDICATE: invoke_ant/2:
     No further documentation available for this predicate.

 -- PREDICATE: ensure_builddir/2:
     No further documentation available for this predicate.

 -- PREDICATE: builddir_clean/2:
     No further documentation available for this predicate.

 -- PREDICATE: wr_template/4:
     No further documentation available for this predicate.

 -- PREDICATE: generate_version_auto/2:
     No further documentation available for this predicate.

 -- PREDICATE: generate_config_auto/2:
     No further documentation available for this predicate.

 -- PREDICATE: print_clauses_to_file/2:
     No further documentation available for this predicate.

 -- PREDICATE: update_file_from_clauses/3:
     No further documentation available for this predicate.

 -- PREDICATE: update_file_from_string/3:
     No further documentation available for this predicate.

 -- PREDICATE: add_rpath/3:
     No further documentation available for this predicate.

 -- PREDICATE: third_party_aux/3:
     No further documentation available for this predicate.

 -- PREDICATE: update_stat_config_sh/2:
     No further documentation available for this predicate.

 -- PREDICATE: remove_dir_nofail/1:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'messages_aux', 'config_common', 'third_party_install', 'eng_defs'.
   - System library modules:

     'pathnames', 'bundle_flags', 'bundle_paths', 'messages',
     'logged_process', 'source_tree', 'system_extra', 'text_template',
     'bundle_info', 'terms', 'format', 'system', 'aggregates', 'write',
     'hiordlib', 'stream_utils', 'lists', 'process', 'llists'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'fsyntax', 'hiord'.

Installation
************

Author(s): The Ciao Development Team.

This module implements basic operations for installing and uninstalling
the contents of a bundle (source and binaries).

The installation copy files from the build area to the installation area
('inst_ciao_root') and (optionally and if needed) creates activation
symbolic links from standard installation directories (e.g.,
'/usr/local/bin').

It supports stagged installations to temporary locations (see
'rootprefix/1').

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(install_aux)).'
   * Exports:

        - Predicates:

          'perms/1', 'instype/1', 'inst_ciao_root/1',
          'inst_bundle_path/3', 'inst_builddir_path/2',
          'inst_cmd_path/4', 'inst_cmd_path/4', 'final_ciao_root/1',
          'final_cmd_path/4', 'final_bundle_path/3',
          'final_builddir_path/3', 'active_bindir/1', 'active_docdir/2',
          'active_cmd_path/3', 'install_bin_dirs/1',
          'uninstall_bin_dirs/1', 'install_bundlereg/1',
          'uninstall_bundlereg/1', 'install_cachedir/1',
          'uninstall_cachedir/1', 'rootprefix/1', 'instdir_install/1',
          'instdir_uninstall/1', 'eng_active_bld/1', 'install_doc/3',
          'uninstall_doc/3'.

Documentation on exports
========================

 -- PREDICATE: perms/1:
     No further documentation available for this predicate.

 -- PREDICATE: instype/1:
     No further documentation available for this predicate.

 -- PREDICATE: inst_ciao_root/1:
     No further documentation available for this predicate.

 -- PREDICATE: inst_bundle_path/3:
     No further documentation available for this predicate.

 -- PREDICATE: inst_builddir_path/2:
     No further documentation available for this predicate.

 -- PREDICATE: inst_cmd_path/4:
     No further documentation available for this predicate.

 -- PREDICATE: inst_cmd_path/4:
     No further documentation available for this predicate.

 -- PREDICATE: final_ciao_root/1:
     No further documentation available for this predicate.

 -- PREDICATE: final_cmd_path/4:
     No further documentation available for this predicate.

 -- PREDICATE: final_bundle_path/3:
     No further documentation available for this predicate.

 -- PREDICATE: final_builddir_path/3:
     No further documentation available for this predicate.

 -- PREDICATE: active_bindir/1:
     No further documentation available for this predicate.

 -- PREDICATE: active_docdir/2:
     No further documentation available for this predicate.

 -- PREDICATE: active_cmd_path/3:
     No further documentation available for this predicate.

 -- PREDICATE: install_bin_dirs/1:
     No further documentation available for this predicate.

 -- PREDICATE: uninstall_bin_dirs/1:
     No further documentation available for this predicate.

 -- PREDICATE: install_bundlereg/1:
     No further documentation available for this predicate.

 -- PREDICATE: uninstall_bundlereg/1:
     No further documentation available for this predicate.

 -- PREDICATE: install_cachedir/1:
     No further documentation available for this predicate.

 -- PREDICATE: uninstall_cachedir/1:
     No further documentation available for this predicate.

 -- PREDICATE: rootprefix/1:

     Usage: 'rootprefix(DestDir)'

     'DestDir' is the prefix that is prepended to each (un)install
     target (useful for packaged bundle creation)

 -- PREDICATE: instdir_install/1:
     No further documentation available for this predicate.

 -- PREDICATE: instdir_uninstall/1:
     No further documentation available for this predicate.

 -- PREDICATE: eng_active_bld/1:
     No further documentation available for this predicate.

 -- PREDICATE: install_doc/3:
     No further documentation available for this predicate.

 -- PREDICATE: uninstall_doc/3:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'builder_aux', 'config_common', 'manifest_compiler', 'ciaoc_aux',
     'builder_flags', 'eng_defs', 'lpdoc_aux', 'info_installer'.
   - System library modules:

     'pathnames', 'bundle_paths', 'messages', 'source_tree',
     'system_extra', 'system', 'bundle_flags', 'streams'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'fsyntax', 'hiord'.

Basic support for CMake
***********************

Author(s): Jose F. Morales.

This module provides some very basic functionality to interface with the
CMake (https://cmake.org) build automation system from the Ciao

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(cmake_aux)).'
   * Exports:

        - Predicates:

          'b_cmake/4'.

Documentation on exports
========================

 -- PREDICATE: b_cmake/4:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'eng_defs'.
   - System library modules:

     'process', 'bundle_paths', 'system_extra'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'fsyntax', 'hiord', 'dcg'.

Installation of info files
**************************

Author(s): The Ciao Development Team.

This module defines predicates to update (register and unregister) the
'dir' Info directory files.

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(info_installer)).'
   * Exports:

        - Predicates:

          'dirfile_install_info/2', 'dirfile_uninstall_info/2'.

Documentation on exports
========================

 -- PREDICATE: dirfile_install_info/2:

     Usage: 'dirfile_install_info(InfoFile,TargetDir)'

     Includes 'InfoFile' in the 'dir' file at 'TargetDir'.  If no 'dir'
     file exist, a default one is created.

 -- PREDICATE: dirfile_uninstall_info/2:

     Usage: 'dirfile_uninstall_info(InfoFile,TargetDir)'

     Removes 'InfoFile' from the 'dir' file at 'TargetDir'.

Documentation on imports
========================

This module has the following direct dependencies:
   - System library modules:

     'pathnames', 'process', 'system'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'regtypes', 'fsyntax'.

Register/unregister code in scripts (for bash, csh, emacs, etc.)
****************************************************************

Author(s): Jose F. Morales, The Ciao Development Team.

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(register_in_script)).'
   * Exports:

        - Predicates:

          'register_in_script/3', 'unregister_from_script/2'.

Documentation on exports
========================

 -- PREDICATE: register_in_script/3:

     Usage: 'register_in_script(File,CommentMark,Code)'

     Inserts 'Code' in the script file 'File'.  Code is surrounded by
     special comments (starting with 'CommentMark'), that allow
     identifying the inserted code later.  If the 'File' contained some
     inserted code, it is replaced.

 -- PREDICATE: unregister_from_script/2:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - System library modules:

     'system', 'system_extra', 'stream_utils', 'lists'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'regtypes', 'dcg', 'fsyntax',
     'basicmodes'.

Bundle hashing
**************

Author(s): Jose F. Morales, The Ciao Development Team.

This module defines the operations to map the whole bundle source code
to shorter identifiers (which can be precise like cryptohashes for DVCS
or coarse like release date, etc.).

Note: Some functions (like Git commit number) simply ignore uncommited
changes in the source tree.

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(bundle_hash)).'
   * Exports:

        - Predicates:

          'bundle_gen_commit_info/1', 'bundle_commit_info/3'.

Documentation on exports
========================

 -- PREDICATE: bundle_gen_commit_info/1:

     Usage:

     Extract and save the commit information metadata

 -- PREDICATE: bundle_commit_info/3:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'builder_flags'.
   - System library modules:

     'native_props', 'datafacts_rt', 'stream_utils', 'system',
     'system_extra', 'terms', 'pathnames', 'bundle_paths',
     'bundle_info', 'vcs_svn', 'version_strings', 'vcs_git'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'basicmodes', 'nativeprops',
     'fsyntax', 'hiord', 'regtypes', 'datafacts'.

C header detection
******************

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(detcheader)).'
   * Exports:

        - Predicates:

          'detect_c_headers/1'.

Documentation on exports
========================

 -- PREDICATE: detect_c_headers/1:

     Usage:

     Succeeds if all the c header files in the argument are valid.
        - The following properties should hold at call time:

          'Arg1' is a list of 'filename's.  ('basic_props:list/2')

Documentation on imports
========================

This module has the following direct dependencies:
   - System library modules:

     'lists', 'stream_utils', 'foreign_compilation', 'system',
     'system_extra', 'process', 'port_reify', 'c_itf_props'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'modes', 'dcg'.

Messages for the build process
******************************

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(messages_aux)).'
   * Exports:

        - Predicates:

          'cmd_message/3', 'dmc_message/3', 'normal_message/2',
          'verbose_message/2'.

Documentation on exports
========================

 -- PREDICATE: cmd_message/3:
     No further documentation available for this predicate.

 -- PREDICATE: dmc_message/3:
     No further documentation available for this predicate.

 -- PREDICATE: normal_message/2:
     No further documentation available for this predicate.

 -- PREDICATE: verbose_message/2:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'config_common'.
   - System library modules:

     'format', 'lists'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'regtypes', 'hiord'.

Auxiliary code for user interaction
***********************************

Author(s): The Ciao Development Team.

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(interactive_aux)).'
   * Exports:

        - Predicates:

          'ask_option_value/6', 'ask_yesno/1'.

Documentation on exports
========================

 -- PREDICATE: ask_option_value/6:

     Usage:
     'ask_option_value(Description,Name,ValidValues,DefaultValue,PreviousValue,Value)'

     Ask (interactively) for a value for variable 'Name'.  Repeat until
     the user provides one of the 'ValidValues', or chose
     'PreviousValue' if none was provided.
        - Call and exit should be compatible with:

          'Description' is a string (a list of character codes).
          ('basic_props:string/1')

          'Name' is an atom.  ('basic_props:atm/1')

          'ValidValues' is a list of 'term's.  ('basic_props:list/2')

          'DefaultValue' is any term.  ('basic_props:term/1')

          'PreviousValue' is any term.  ('basic_props:term/1')

          'Value' is any term.  ('basic_props:term/1')
        - The following properties should hold at call time:

          'Description' is currently a term which is not a free
          variable.  ('term_typing:nonvar/1')

          'Name' is currently a term which is not a free variable.
          ('term_typing:nonvar/1')

          'ValidValues' is currently a term which is not a free
          variable.  ('term_typing:nonvar/1')

          'DefaultValue' is currently a term which is not a free
          variable.  ('term_typing:nonvar/1')

          'PreviousValue' is currently a term which is not a free
          variable.  ('term_typing:nonvar/1')

          'Value' is a free variable.  ('term_typing:var/1')

 -- PREDICATE: ask_yesno/1:
     No further documentation available for this predicate.

Documentation on imports
========================

This module has the following direct dependencies:
   - System library modules:

     'lists', 'stream_utils'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'basicmodes', 'dcg', 'fsyntax',
     'hiord'.

Bundle configuration
********************

Author(s): The Ciao Development Team.

This module computes the values of bundle configuration flags (
'bundle_flags') based on configuration parameters the configuration
rules ('Manifest/*.hooks.pl' files).

TODO: Write documentation for the syntax and semantics of configuration
rules.

The configuration process may invoke external configuration tools if
required.

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(bundle_configure)).'
   * Exports:

        - Predicates:

          'check_builder_update/0', 'bundle_has_config/1',
          'bundleset_configure/2', 'config_set_flag/2',
          'config_get_flag/2', 'config_list_flags/1',
          'config_describe_flag/1',
          'set_prolog_flags_from_bundle_flags/1'.
        - Multifiles:

          'm_bundlehook_decl/3', 'm_bundlehook_do/3',
          'm_third_party_name/1', 'm_third_party_version/2',
          'm_third_party_source_url/2', 'm_third_party_source_md5/2',
          'm_third_party_patch/2', 'm_third_party_build_system/2',
          'm_third_party_option1/2', 'm_third_party_option2/3',
          'm_third_party_custom_configure/2',
          'm_third_party_custom_build/2',
          'm_third_party_custom_install/2', 'm_bundle_config_call/2',
          'm_bundle_config_entry/3', 'm_bundle_foreign_config_tool/3',
          'm_bundle_foreign_dep/4'.

Documentation on exports
========================

 -- PREDICATE: check_builder_update/0:

     Usage:

     Detect if the running builder needs an update.

 -- PREDICATE: bundle_has_config/1:
     No further documentation available for this predicate.

 -- PREDICATE: bundleset_configure/2:

     Usage: 'bundleset_configure(BundleSet,Flags)'

     Configure the bundles specified in 'BundleSet' using their
     configuration rules and the input provided by 'Flags' and/or user
     interaction (if 'interactive_config' flag is specified).

 -- PREDICATE: config_set_flag/2:
     No further documentation available for this predicate.

 -- PREDICATE: config_get_flag/2:
     No further documentation available for this predicate.

 -- PREDICATE: config_list_flags/1:
     No further documentation available for this predicate.

 -- PREDICATE: config_describe_flag/1:
     No further documentation available for this predicate.

 -- PREDICATE: set_prolog_flags_from_bundle_flags/1:
     No further documentation available for this predicate.

Documentation on multifiles
===========================

 -- PREDICATE: m_bundlehook_decl/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundlehook_do/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_name/1:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_version/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_source_url/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_source_md5/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_patch/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_build_system/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_option1/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_option2/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_custom_configure/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_custom_build/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_third_party_custom_install/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_config_call/2:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_config_entry/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_foreign_config_tool/3:
     No further documentation available for this predicate.  The
     predicate is multifile.

 -- PREDICATE: m_bundle_foreign_dep/4:
     No further documentation available for this predicate.  The
     predicate is multifile.

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'builder_flags', 'interactive_aux', 'car_maker',
     'manifest_compiler'.
   - System library modules:

     'datafacts_rt', 'lists', 'process', 'messages', 'port_reify',
     'bundle_flags', 'version_strings', 'system_extra', 'bundle_paths',
     'system', 'stream_utils', 'aggregates', 'hiordlib', 'bundle_info'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'assertions',
     'assertions/assertions_basic', 'basicmodes', 'fsyntax', 'hiord',
     'datafacts'.

Bundle fetch
************

Author(s): Jose F. Morales.

This module implements support for fetching bundles and their
dependencies from remote locations (e.g., the network).

The predicate 'bundle_fetch/2' fetches a bundle and its dependencies, as
follows:

   * if the bundle is in a non-top workspace, stops fetching (and do not
     try to fetch dependencies)
   * if the bundle is missing, retreive and store it at the top
     workspace (see 'CIAOPATH' environment)
   * if the bundle is in the top workspace, skips fetching
   * try fetch bundle dependencies

A fetched bundle is automatically marked to distinguish them from user
bundles, which are manually written by the user.  It is possible to
fetch a user bundle, e.g., to retreive all their dependencies.

Fetched bundles can be removed with 'bundle_rm/1'.  Removing a user
bundle is not allowed with 'bundle_rm/1' (it must be done manually).

The location and fetch protocol is automatically recognized based on
bundle aliases.  See 'bundle_src_origin/2' for translation from bundle
aliases to recognized origins (e.g., 'ciao-lang.org/foo' downloads and
uncompress a 'git' archive).

Usage and interface
===================

   * Library usage:

     ':- use_module(ciaobld(bundle_fetch)).'
   * Exports:

        - Predicates:

          'add_bundle_origin/2', 'get_bundle_origin/2',
          'bundle_fetch_cleanup/0', 'check_bundle_alias/3',
          'bundle_fetch/2', 'bundle_rm/1'.

Documentation on exports
========================

 -- PREDICATE: add_bundle_origin/2:

     Usage: 'add_bundle_origin(Bundle,Origin)'

     Select the origin for the given bundle name

 -- PREDICATE: get_bundle_origin/2:

     Usage: 'get_bundle_origin(Bundle,Origin)'

     Obtain the origin for a bundle (for fetching).  Use the default
     origin if unknown ( 'default_origin/2').

 -- PREDICATE: bundle_fetch_cleanup/0:

     Usage:

     Cleanup the bundle fetch state

 -- PREDICATE: check_bundle_alias/3:

     Usage: 'check_bundle_alias(BundleAlias,Origin,Bundle)'

     Given a URL-like 'BundleAlias', obtain its 'Origin' term for fetch
     and the bundle name 'Name'.  Throws an exception if malformed and
     fails silently if it is not a URL-like alias.
        - The following properties should hold at call time:

          'BundleAlias' is currently a term which is not a free
          variable.  ('term_typing:nonvar/1')

          'Origin' is a free variable.  ('term_typing:var/1')

          'Bundle' is a free variable.  ('term_typing:var/1')

 -- PREDICATE: bundle_fetch/2:

     Usage: 'bundle_fetch(Bundle,Fetched)'

     Fetch 'Bundle' and all its dependencies.  'Fetched' is the list of
     newly fetched bundles.
        - The following properties should hold at call time:

          'Bundle' is currently a term which is not a free variable.
          ('term_typing:nonvar/1')

          'Fetched' is a free variable.  ('term_typing:var/1')

 -- PREDICATE: bundle_rm/1:
     No further documentation available for this predicate.

Documentation on internals
==========================

 -- PREDICATE: default_origin/2:

     Usage: 'default_origin(Bundle,Origin)'

     Default origin when none is specified:
          default_origin(Bundle,Origin) :-
              path_concat('github.com/ciao-lang',Bundle,Path),
              Origin=github(Path,master).

Documentation on imports
========================

This module has the following direct dependencies:
   - Application modules:

     'bundle_scan', 'messages_aux', 'manifest_compiler'.
   - System library modules:

     'datafacts_rt', 'lists', 'terms', 'pathnames', 'process',
     'http_get', 'system', 'system_extra', 'source_tree', 'bundle_info',
     'aggregates'.
   - Packages:

     'prelude', 'initial', 'condcomp', 'dcg', 'fsyntax', 'hiord',
     'assertions', 'assertions/assertions_basic', 'regtypes',
     'isomodes', 'datafacts'.

Publish from a mono-repository
******************************

Author(s): Jose F. Morales.

This tool allows publishing pristine views of an annotated git
mono-repository.  An annotated git repository contains 'NODISTRIBUTE'
empty files that mark directories that must not be visible in a pristine
copy.

This tool is tailored for the 'ciao-devel' mono-repository but it could
be easily generalized for other repositories.

Usage
=====

Use 'ciao publish list' to list publishable bundles from the Ciao devel
repository (either the main 'ciao' or some bundles at 'bndls/').  E.g.:
     $ ciao publish list

Publishing code is performed by the 'commit' and 'push' operations.  Use
the 'help' option to view other possible commmands.

Example for publishing the bundle at the current directory (when run at
the Ciao root directory the special 'ciao' bundle is selected, which
contains 'core' and 'builder'):
     $ ciao publish pull
     $ ciao publish commit
     << (please review commits) >>
     $ ciao publish push

A command may be followed by a target bundle name to specify a different
bundle.  Example for publishing 'ciao_emacs':
     $ ciao publish pull ciao_emacs
     $ ciao publish commit ciao_emacs
     << (please review commits) >>
     $ ciao publish push ciao_emacs

The first time that 'commit' is performed, it will require a first
commit number.  This is not needed for 'squash'.

You can use the '--all' option to perform a command on all publishable
bundles (see '--help' for more info), or use shell scripts.

Examples on all bundles:
     << Consult the status of all publishable bundles >>
     $ ciao publish status --all

     << Pull all public repositories (previous to publishing) >>
     $ ciao publish pull --all

     << Commit all publishable changes >>
     $ ciao publish commit --all

     << Push to the public repository >>
     $ ciao publish push --all

   * The source is fetched from the repository (not from the checkout).
   * Clones of publishing repos are kept at '$HOME/REPOS-ciao-publish'
     (with some metadata to speedup detection of unpublished commits).

Additional files for publishing
===============================

Other directories:
     ci-scripts/      Scripts for CI
     ci-status/       Scripts for checking the status of CI
     etc/ciao-download-stats.sh
                      Download statistics

Contribution from public repositories
=====================================

Assume that Bob maintains the private Ciao repository and Alice wants to
contribute to it.  This is the typical workflow for contributing to the
project preserving authorship:
   * Alice: clone public Git repository ('github.com/ciao-lang/ciao')
   * Alice: make some changes and commit them
   * Alice: format patches using 'git format-patch' (never push them!)
          $ git format-patch HEAD^n # where n is the number of commits not in master
   * Alice: send the '????-*.patch' files via email to Bob
   * Bob: apply back the changes in the private repository with

          $ git am < 0001-*.patch
          $ git am < 0002-*.patch
          $ ...

   * Bob: check with 'git log' that the code is pushed correctly
   * Bob: do 'ciao publish pull', 'ciao publish commit', and 'ciao
     publish push'

   * Alice: do 'git pull' and 'git rebase -i'.  The first command will
     create a merge commit.  The second command will break.  After some
     'git rebase --continue' it will end.  If everything is fine there
     will be no unpushed changes to master and all new commits will be
     authored as Alice.

Merging github pull requests
============================

You can follow the same steps as in the previous section, just obtaining
the patches from this custom URL
'https://github.com/ciao-lang/ciao/pull/NUMBER.patch'.

References
**********

(this section is empty)

Property Index
**************

Regular Type Index
******************

Declaration Index
*****************

Global Index
************

This is a global index containing pointers to places where concepts,
predicates, modes, properties, types, applications, authors, etc., are
referred to in the text of the document.