<commit_before># Reference

## File types

### header(*name*)

Create a reference to an existing header named *name*. This is useful if you'd
like to [install](#install-all) a single header file for your project.

### header_directory(*directory*, [*system*])

Create a reference to a *directory* containing header files for the project.
This can then be used in the *include* argument when
[compiling](#object_filename-file-extra_deps) a source file. If *system* is
*True*, this directory will be treated as a
[system directory](https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html) for
compilers that support this.

### source_file(*name*, [*lang*])

Create a reference to an existing source file named *name*. If *lang* is not
specified, the language of the file is inferred from its extension. Generally,
this function is only necessary when running commands that take a source file
as an argument, e.g. running a Python script; this allows you to specify that
the file is found in the *source directory*. In other cases, a plain string will
automatically get converted to a *source_file*.

## Build steps

!!! note
    For build steps which produce an actual file, the exact name of the output
    file is determined by the platform you're running on. For instance, when
    building an executable file named "foo" on Windows, the resulting file will
    be `foo.exe`.

### alias(*name*, [*deps*])

Create a build step named *name* that performs no actions on its own. Instead,
it just runs its dependencies listed in *deps* as necessary. This build step is
useful for grouping common steps together, e.g. the common `make all` command.

### command(*name*, *cmd*|*cmds*, [*environment*], [*extra_deps*])

Create a build step that runs a list of arbitrary commands, specified in either
*cmd* or *cmds*; *cmd* takes a single command, whereas *cmds* takes a list of
commands. Each command may either be a string to be parsed according to shell
rules or a list of arguments to be passed directly to the process.

You may also pass a dict to *environment* to set environment variables for the
commands. These override any environment variables set on the command line.

### executable(*name*, [*files*, ..., [*extra_deps*]])

Create a build step that builds an executable file named *name*. *files* is the
list of source (or object) files to link. If an element of *files* is a source<commit_msg>Add docs for whole_archive()<commit_after># Reference

## File types

### header(*name*)

Create a reference to an existing header named *name*. This is useful if you'd
like to [install](#install-all) a single header file for your project.

### header_directory(*directory*, [*system*])

Create a reference to a *directory* containing header files for the project.
This can then be used in the *include* argument when
[compiling](#object_filename-file-extra_deps) a source file. If *system* is
*True*, this directory will be treated as a
[system directory](https://gcc.gnu.org/onlinedocs/cpp/System-Headers.html) for
compilers that support this.

### source_file(*name*, [*lang*])

Create a reference to an existing source file named *name*. If *lang* is not
specified, the language of the file is inferred from its extension. Generally,
this function is only necessary when running commands that take a source file
as an argument, e.g. running a Python script; this allows you to specify that
the file is found in the *source directory*. In other cases, a plain string will
automatically get converted to a *source_file*.

### whole_archive(*name*)

Create a [whole-archive](http://linux.die.net/man/1/ld) from an existing static
library named *name*. This ensure that *every* object file in the library is
included, rather than just the ones whose symbols are referenced. This is
typically used to turn a static library into a shared library.

!!! note
    The MSVC linker doesn't have a way of expressing this directive, so
    *whole_archive* can't be used with it.

## Build steps

!!! note
    For build steps which produce an actual file, the exact name of the output
    file is determined by the platform you're running on. For instance, when
    building an executable file named "foo" on Windows, the resulting file will
    be `foo.exe`.

### alias(*name*, [*deps*])

Create a build step named *name* that performs no actions on its own. Instead,
it just runs its dependencies listed in *deps* as necessary. This build step is
useful for grouping common steps together, e.g. the common `make all` command.

### command(*name*, *cmd*|*cmds*, [*environment*], [*extra_deps*])

Create a build step that runs a list of arbitrary commands, specified in either
*cmd* or *cmds*; *cmd* takes a single command, whereas *cmds* takes a list of
commands. Each command may either be a string to be parsed according to shell
rules or a list of arguments to be passed directly to the process.

You may also pass a dict to *environment* to set environment variables for the
commands. These override any environment variables set on the command line.

### executable(*name*, [*files*, ..., [*extra_deps*]])

Create a build step that builds an executable file named *name*. *files* is the
list of source (or object) files to link. If an element of *files* is a source
{'fraction_non_alphanumeric': 0.08802281368821292, 'fraction_numerical': 0.00019011406844106463, 'mean_word_length': 4.480208333333334, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '866982', 'n_tokens_mistral': 1413, 'n_tokens_neox': 1359, 'n_words': 771}