
# Build and Gather

	The two main processes in the Elucid8 framework

<div id="Overview"></div>

## Overview
In general, RakuDoc sources are held in git repositories.  
<span class="para" id="1145b01"></span>However, if the *sources*<a id="Using_the_config_file_it_is_possible_to_rename_nearly_every_directory_and_file_name,_so_the_key_name_in_the_config_file_is_used_here." href="#fn_target_Using_the_config_file_it_is_possible_to_rename_nearly_every_directory_and_file_name,_so_the_key_name_in_the_config_file_is_used_here."><sup>[ 1 ]</sup></a> already contains all the sources, and no sources are kept in repositories, then the `gather-sources` utility need not be used.   
The following steps are then followed for each build sequence:  
  
1.The `gather-sources` utility is used to:  
&nbsp;&nbsp;&nbsp;&nbsp;▹ clone the RakuDoc sources in the website build are under the `repository-store` directory using `gather-sources`.  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;‣ Each repository is specified in the *04.repositories* config file.  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;‣ A repository may contain files for multiple languages.  
&nbsp;&nbsp;&nbsp;&nbsp;▹ create entries in `repo-info` hash to the desired *.rakudoc* files.  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;‣ Files may be selected on a global basis by setting the [with-only](With only filter).  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;‣ Files may be filtered out at the language/repo using `ignore`, files not listed in *ignore* have entries created.  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;‣ Files may be selected at the language/repo using `select`, no other files are let through.  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;‣ *ignore* is applied after *select*, so files in both *select* and *ignore* will be ignored.  
&nbsp;&nbsp;&nbsp;&nbsp;▹ generate from `repo-info` a file called `repository-info-file`, which is stored in `misc`.  
2.The `elucid8-build` utility is then called to:  
&nbsp;&nbsp;&nbsp;&nbsp;▹ update the `file-data-name` file.  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;‣ If the *repository-info-file* file exists, it is the basis for *file-data-name*.  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;‣ If the *repository-info-file* file does not exist, *file-data-name* is built from the files in the *sources* directory.  
&nbsp;&nbsp;&nbsp;&nbsp;▹ render the files in the *sources* directory into the `publication` directory  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;‣ Existing rendered files are updated if  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;⁃ the rendered date is older than the last modification date of the source  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;⁃ the force `-f` flag is set  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;‣ if a *:with-only* list is present in the config file, or *elucid8-build* is called with a *--with-only* argument on the CLI, then only those sources are rendered  
<span class="para" id="7d70087"></span>The build process may be controlled using the following options with *elucid8-build*:   
  
&nbsp;&nbsp;• `--regenerate-from-scratch` = delete the *publication* directory and the *file-data-name* file.  
&nbsp;&nbsp;• `--with-only`&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; = only operate on these files (others in *publication* directory will be untouched).  
&nbsp;&nbsp;• `--f`&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; = ignore the modified attribute.  
&nbsp;&nbsp;• `-v`&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;= get the versions of the *Elucid8-build* and *Rakuast-RakuDoc-Render* distributions.  

<div id="Relation between repository-info-file and file-data-name"></div><div id="Relation_between_repository-info-file_and_file-data-name"></div>

## Relation between repository-info-file and file-data-name
<span class="para" id="18972af"></span>The `repository-info-file` is generated by *gather-sources* and contains information that can be obtained from the repositories and the config.   
<span class="para" id="746549a"></span>`file-data-name` file can be generated from the files in `sources` or from `repository-info-file`.   
<span class="para" id="988a17c"></span>Either there are files in sources, and `repository-info-file` is absent, or vice versa.   
<span class="para" id="bf24e42"></span>However, `file-data-name` contains information about the rendered files as well.   
<span class="para" id="01d0dc4"></span>When `gather-sources` is run, it updates the local repositories, and stores the modified attribute for each file. So, `elucid8-build` needs to update `file-data-name`.   
<div id="License"></div>

## License
Artistic-2.0



<div id="Credits"></div>

## Credits
Richard Hainsworth



----

## Footnotes
1<a id=".<fnTarget>" href="#Using_the_config_file_it_is_possible_to_rename_nearly_every_directory_and_file_name,_so_the_key_name_in_the_config_file_is_used_here."> |^| </a>Using the `config` file it is possible to rename nearly every directory and file name, so the key name in the config file is used here.



----

----

Rendered from docs/Build-Gather.rakudoc/Build-Gather at 21:33 UTC on 2026-07-11

Source last modified at 21:57 UTC on 2025-03-23

