
                                      API


                                  Pirmin Duss


The _api_ file defines the include paths required by users of a project that
produces a library.


Syntax
######

The file consists of an arbitrary number of lines where each line has the
following structure:

! [<directory>:]<selector>[/]

<selector> path is relative to the build directory. The selector comprises the
files and directories to be featured in the api archive of the library. A
trailing slash after the selector denotes all files of a directory.  <directory>
refers to the directory where <selector> files will be installed within the
_api_. In case <directory> is not specified, the path given by <selector> is
used. Otherwise, <directory> will be used and created. This allows for having
files in different _api_ locations compared to the build directory.

When using API archives, Goa adds the following contained directories to the
list of include directories (if they exist and apply to the target architecture):

* include/
* include/spec/x86/
* include/spec/x86_64/
* include/spec/arm_64/
* include/spec/64bit/
!

Note that the build directory also contains an _install_ subdirectory which is
used as a destination directory for running *make install* after a successful
build. When extracting include paths from the install subdirectory, the
_install/_ prefix is removed.


Examples
########

:include/spdlog.h: The file _include/spdlog.h_ from the build directory is added as a single
  header file.

:include/spdlog/: All files found in the directory _include/spdlog_ below the build directory are
  added as artifacts. The relative directory structure is kept intact.

:install/include/spdlog/: All files found in the directory _install/include/spdlog_ below the build
  directory are added as artifacts to _include/spdlog_ of the api archive.

:include:install/lib/glib-2.0/include/glibconfig.h: Install _glibconfig.h_ into
  the _include_ directory of the api archive.

:include/glib:install/include/glib-2.0/glib/: Install all files in
  _install/include/glib-2.0/glib/_ into _include/glib/_.

SEE ALSO
########

add-depot-user, api, artifacts, build-systems, import, index, config, overview, runtime, targets
