=================================
File List Format Reference Manual
=================================

.. contents::
   :local:
   :depth: 4

.. _filelist_abstract:

Abstract
========
The file list is a JSON file that specifes the set of header files to be
parsed. This file is intended to be generated by the build system and passed to
TAPI as an alternative way of specifying headers files that reside in
nondefault locations or locations that do no allow attribution of header files
to a specific dynamic library file. This is why file list are usually used for
dynamic library projects.


.. _filelist_format:

Format
======

Ther are two versions of the file list. The only difference between version 1
and 2 is that version 2 allows project headers as input.

.. _filelist_file_list:

File List v2
------------

This is an example of file list v2:

.. code::

  {
    "version" : "2",
    "headers" : [
      {
        "type" : "public",
        "path" : "/usr/include/bar1.h"
      },
      {
        "type" : "public",
        "path" : "/usr/include/bar2.h"
      },
      {
        "type" : "private",
        "path" : "/usr/local/include/bar3.h"
      },
      {
        "type" : "project",
        "path" : "./src/bar_internal.h"
      }
    ]
  }

Keys:

- :ref:`version <filelist_version>`
- :ref:`headers <filelist_headers>`


.. _filelist_version:

Version
~~~~~~~

The key *version* is required and specifies the file list version.

Example:

.. code::

  version: 2

The only valid values are 1 and 2.


.. _filelist_headers:

Headers
~~~~~~~

The key *headers* is required and specifies a list of header files to parse.
Each header entry consists of the header type and the header path.

Example:

.. code::

  "headers" : [
    {
        "type" : "public",
        "path" : "/usr/include/bar1.h"
    }
    ...
  ]

- :ref:`type <filelist_header_type>`
- :ref:`path <filelist_header_path>`

.. _filelist_header_type:

Header Type
~~~~~~~~~~~

The key *type* specifies the header type and is required. Valid values are
public and private for version 1 file lists and public, private, and project
for version 2 file lists.

Example:

.. code::

    "type" : "public"

.. _filelist_header_path:

Header Path
~~~~~~~~~~~

The key *path* specifies the header path and is required.

Example:

.. code::

  "path" : "/usr/include/bar1.h"
