ifhub/inform7
1
0
Fork 0
mirror of https://github.com/ganelson/inform.git synced 2024-05-04 01:59:41 +03:00
Code Issues Projects Releases Wiki Activity
inform7/docs/supervisor-module/1-ic.html
Graham Nelson 81a287a873 Repairing damaged directory extensions
2023-03-21 22:45:28 -07:00

695 lines
117 KiB
HTML
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Inbuild Control</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
<meta name="viewport" content="width=device-width initial-scale=1">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Language" content="en-gb">
<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<script>
function togglePopup(material_id) {
var popup = document.getElementById(material_id);
popup.classList.toggle("show");
}
</script>
<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
</head>
<body class="commentary-font">
<nav role="navigation">
<h1><a href="../index.html">
<img src="../docs-assets/Inform.png" height=72">
</a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../indocn.html">indoc</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
<li><a href="../inrtpsn.html">inrtps</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=18> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="../../../inweb/index.html">inweb</a></li>
<li><a href="../../../intest/index.html">intest</a></li>
</ul>
</nav>
<main role="main">
<!--Weave of 'Inbuild Control' generated by Inweb-->
<div class="breadcrumbs">
<ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../inbuildn.html">Inbuild Modules</a></li><li><a href="index.html">supervisor</a></li><li><a href="index.html#1">Chapter 1: Setting Up</a></li><li><b>Inbuild Control</b></li></ul></div>
<p class="purpose">Who shall supervise the supervisor? This section of code will.</p>
<ul class="toc"><li><a href="1-ic.html#SP1">&#167;1. Phases</a></li><li><a href="1-ic.html#SP3">&#167;3. Startup phase</a></li><li><a href="1-ic.html#SP4">&#167;4. Configuration phase</a></li><li><a href="1-ic.html#SP8">&#167;8. The Pretinkering, Tinkering, Nested and Projected phases</a></li><li><a href="1-ic.html#SP10">&#167;10. The Graph Construction and Operational phases</a></li><li><a href="1-ic.html#SP11">&#167;11. The nest list</a></li><li><a href="1-ic.html#SP17">&#167;17. The shared project</a></li></ul><hr class="tocbar">
<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. Phases. </b>The <a href="index.html" class="internal">supervisor</a> module provides services to the parent tool.
</p>
<p class="commentary">This section defines how the parent communicates with us to get everything
set up correctly. Although nothing at all clever happens in this code, it
requires careful sequencing to avoid invisible errors coming in because
function X assumes that function Y has already been called, or perhaps that
it never will be again. The <a href="index.html" class="internal">supervisor</a> module therefore runs through a
number of named "phases" on its way to reaching fully-operational status,
at which time the parent can freely use its facilities.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">STARTUP_INBUILD_PHASE</span><span class="plain-syntax"> </span><span class="identifier-syntax">from</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">CONFIGURATION_INBUILD_PHASE</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">PRETINKERING_INBUILD_PHASE</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">TINKERING_INBUILD_PHASE</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">NESTED_INBUILD_PHASE</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">TARGETED_INBUILD_PHASE</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">GRAPH_CONSTRUCTION_INBUILD_PHASE</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">OPERATIONAL_INBUILD_PHASE</span>
</pre>
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>We're going to use the following assertions to make sure we don't slip up.
Some functions run only in some phases. Phases can be skipped, but not taken
out of turn.
</p>
<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="identifier-syntax">RUN_ONLY_IN_PHASE</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> &lt; </span><span class="identifier-syntax">P</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"too soon"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> &gt; </span><span class="identifier-syntax">P</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"too late"</span><span class="plain-syntax">);</span>
<span class="definition-keyword">define</span> <span class="identifier-syntax">RUN_ONLY_FROM_PHASE</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> &lt; </span><span class="identifier-syntax">P</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"too soon"</span><span class="plain-syntax">);</span>
<span class="definition-keyword">define</span> <span class="identifier-syntax">RUN_ONLY_BEFORE_PHASE</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> &gt;= </span><span class="identifier-syntax">P</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"too late"</span><span class="plain-syntax">);</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> = </span><span class="constant-syntax">STARTUP_INBUILD_PHASE</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::enter_phase</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">p</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">p</span><span class="plain-syntax"> &lt;= </span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"phases out of sequence"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> = </span><span class="identifier-syntax">p</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. Startup phase. </b>The following is called when the <a href="index.html" class="internal">supervisor</a> module starts up.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">extension_genre</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">extension_bundle_genre</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">kit_genre</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">language_genre</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pipeline_genre</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">project_bundle_genre</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">project_file_genre</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">inbuild_genre</span><span class="plain-syntax"> *</span><span class="identifier-syntax">template_genre</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::start</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">Supervisor::start</span></span>:<br/>Supervisor Module - <a href="1-sm.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="4-em.html#SP2" class="function-link"><span class="function-syntax">ExtensionManager::start</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="4-ebm.html#SP1" class="function-link"><span class="function-syntax">ExtensionBundleManager::start</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="4-km.html#SP1" class="function-link"><span class="function-syntax">KitManager::start</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="4-lm.html#SP1" class="function-link"><span class="function-syntax">LanguageManager::start</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="4-pm.html#SP1" class="function-link"><span class="function-syntax">PipelineManager::start</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="4-pbm.html#SP1" class="function-link"><span class="function-syntax">ProjectBundleManager::start</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="4-pfm.html#SP1" class="function-link"><span class="function-syntax">ProjectFileManager::start</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="4-tm.html#SP1" class="function-link"><span class="function-syntax">TemplateManager::start</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="3-is.html#SP1" class="function-link"><span class="function-syntax">InterSkill::create</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="3-is2.html#SP1" class="function-link"><span class="function-syntax">Inform7Skill::create</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="3-is3.html#SP1" class="function-link"><span class="function-syntax">Inform6Skill::create</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="3-is4.html#SP1" class="function-link"><span class="function-syntax">InblorbSkill::create</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><a href="6-cs.html#SP5" class="function-link"><span class="function-syntax">ControlStructures::create_standard</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> = </span><span class="constant-syntax">CONFIGURATION_INBUILD_PHASE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="1-ic.html#SP5" class="function-link"><span class="function-syntax">Supervisor::set_defaults</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. Configuration phase. </b>Initially, then, we are in the configuration phase. When the parent defines
its command-line options, we expect it to call <span class="extract"><span class="extract-syntax">Supervisor::declare_options</span></span>
so that we can define further options &mdash; this provides the large set of
common options found in both <span class="extract"><span class="extract-syntax">inform7</span></span> and <span class="extract"><span class="extract-syntax">inbuild</span></span>, our two possible parents.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::declare_options</span><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_IN_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">CONFIGURATION_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="1-ic.html#SP4_2" class="named-paragraph-link"><span class="named-paragraph">Declare Inform-related options</span><span class="named-paragraph-number">4.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="1-ic.html#SP4_4" class="named-paragraph-link"><span class="named-paragraph">Declare resource-related options</span><span class="named-paragraph-number">4.4</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="1-ic.html#SP4_6" class="named-paragraph-link"><span class="named-paragraph">Declare Inter-related options</span><span class="named-paragraph-number">4.6</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4_1" class="paragraph-anchor"></a><b>&#167;4.1. </b>These options all predate the 2015-20 reworking of the compiler, and their
names are a series of historical accidents. <span class="extract"><span class="extract-syntax">-format</span></span> in particular works in
a clunky sort of way and should perhaps be deprecated in favour of some
better way to choose a virtual machine to compile to.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">INBUILD_INFORM_CLSG</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">PROJECT_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">BASIC_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">DEBUG_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">RELEASE_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">FORMAT_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">SOURCE_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">O_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">CENSUS_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">RNG_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">CASE_CLSW</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4_2" class="paragraph-anchor"></a><b>&#167;4.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Declare Inform-related options</span><span class="named-paragraph-number">4.2</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::begin_group</span><span class="plain-syntax">(</span><span class="constant-syntax">INBUILD_INFORM_CLSG</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"for translating Inform source text to Inter"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">PROJECT_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"project"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"work within the Inform project X"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">BASIC_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"basic"</span><span class="plain-syntax">, </span><span class="constant-syntax">1</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"use Basic Inform language"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_boolean_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">DEBUG_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"debug"</span><span class="plain-syntax">, </span><span class="constant-syntax">1</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"compile with debugging features even on a Release"</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_boolean_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">RELEASE_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"release"</span><span class="plain-syntax">, </span><span class="constant-syntax">1</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"compile a version suitable for a Release build"</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_textual_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">FORMAT_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"format"</span><span class="plain-syntax">, </span><span class="constant-syntax">1</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"compile to the format X (default is Inform6/32)"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">SOURCE_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"source"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"use file X as the Inform source text"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">O_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"o"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"use file X as the compiled output (not for use with -project)"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_boolean_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">CENSUS_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"census"</span><span class="plain-syntax">, </span><span class="constant-syntax">1</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"perform an extensions census"</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_boolean_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">RNG_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"rng"</span><span class="plain-syntax">, </span><span class="constant-syntax">1</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"fix the random number generator of the story file (for testing)"</span><span class="plain-syntax">, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">CASE_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"case"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"make any source links refer to the source in extension example X"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::end_group</span><span class="plain-syntax">();</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-ic.html#SP4">&#167;4</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP4_3" class="paragraph-anchor"></a><b>&#167;4.3. </b>Again, except for <span class="extract"><span class="extract-syntax">-nest</span></span>, these go back to the mid-2010s.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">INBUILD_RESOURCES_CLSG</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">NEST_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">INTERNAL_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">EXTERNAL_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">TRANSIENT_CLSW</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4_4" class="paragraph-anchor"></a><b>&#167;4.4. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Declare resource-related options</span><span class="named-paragraph-number">4.4</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::begin_group</span><span class="plain-syntax">(</span><span class="constant-syntax">INBUILD_RESOURCES_CLSG</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"for locating resources in the file system"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">NEST_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"nest"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"add the nest at pathname X to the search list"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">INTERNAL_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"internal"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"use X as the location of built-in material such as the Standard Rules"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">EXTERNAL_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"external"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"use X as the user's home for installed material such as extensions"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">TRANSIENT_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"transient"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"use X for transient data such as the extensions census"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::end_group</span><span class="plain-syntax">();</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-ic.html#SP4">&#167;4</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP4_5" class="paragraph-anchor"></a><b>&#167;4.5. </b>These are all new in 2020. They are not formally shared with the <span class="extract"><span class="extract-syntax">inter</span></span> tool,
but <span class="extract"><span class="extract-syntax">-pipeline-file</span></span> and <span class="extract"><span class="extract-syntax">-variable</span></span> have the same effect as they would there.
</p>
<pre class="definitions code-font"><span class="definition-keyword">enum</span> <span class="constant-syntax">INBUILD_INTER_CLSG</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">KIT_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">PIPELINE_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">PIPELINE_FILE_CLSW</span>
<span class="definition-keyword">enum</span> <span class="constant-syntax">PIPELINE_VARIABLE_CLSW</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4_6" class="paragraph-anchor"></a><b>&#167;4.6. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Declare Inter-related options</span><span class="named-paragraph-number">4.6</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::begin_group</span><span class="plain-syntax">(</span><span class="constant-syntax">INBUILD_INTER_CLSG</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"for tweaking code generation from Inter"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">KIT_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"kit"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"include Inter code from the kit called X"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">PIPELINE_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"pipeline"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"specify code-generation pipeline by name (default is \"compile\")"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">PIPELINE_FILE_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"pipeline-file"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"specify code-generation pipeline as file X"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::declare_switch</span><span class="plain-syntax">(</span><span class="constant-syntax">PIPELINE_VARIABLE_CLSW</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"variable"</span><span class="plain-syntax">, </span><span class="constant-syntax">2</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">L</span><span class="string-syntax">"set pipeline variable X (in form name=value)"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::end_group</span><span class="plain-syntax">();</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-ic.html#SP4">&#167;4</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b>Use of the above options will cause the following global variables to be
set appropriately.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">inter_pipeline_file</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">transpiled_output_file</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">dictionary</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pipeline_vars</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">shared_transient_resources</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">this_is_a_debug_compile</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment-syntax"> Destined to be compiled with debug features</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">this_is_a_release_compile</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment-syntax"> Omit sections of source text marked not for release</span>
<span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">output_format</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">; </span><span class="comment-syntax"> What story file we will eventually have</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">census_mode</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment-syntax"> Running only to update extension documentation</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">repair_mode</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">; </span><span class="comment-syntax"> Automatically fix missing or damaged extension metadata</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">rng_seed_at_start_of_play</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">; </span><span class="comment-syntax"> The seed value, or 0 if not seeded</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::set_defaults</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">Supervisor::set_defaults</span></span>:<br/><a href="1-ic.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_IN_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">CONFIGURATION_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">ifdef</span><span class="plain-syntax"> </span><span class="identifier-syntax">PIPELINE_MODULE</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">pipeline_vars</span><span class="plain-syntax"> = </span><span class="identifier-syntax">ParsingPipelines::basic_dictionary</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"output.ulx"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax"> </span><a href="1-ic.html#SP6" class="function-link"><span class="function-syntax">Supervisor::set_inter_pipeline</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"compile"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. </b>The pipeline name can be set not only here but also by <span class="extract"><span class="extract-syntax">inform7</span></span> much
later on (way past the configuration stage), if it reads a sentence like:
</p>
<blockquote>
<p>Use inter pipeline "special".</p>
</blockquote>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">inter_pipeline_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::set_inter_pipeline</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">Supervisor::set_inter_pipeline</span></span>:<br/><a href="1-ic.html#SP5">&#167;5</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">inter_pipeline_name</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">inter_pipeline_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::new</span><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">Str::clear</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_pipeline_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_pipeline_name</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. </b>The <a href="index.html" class="internal">supervisor</a> module itself doesn't parse command-line options: that's for
the parent to do, using code from Foundation. When the parent finds an option
it doesn't know about, that will be one of ours, so it should call the following:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::option</span><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">val</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">arg</span><span class="plain-syntax">, </span><span class="reserved-syntax">void</span><span class="plain-syntax"> *</span><span class="identifier-syntax">state</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_IN_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">CONFIGURATION_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">switch</span><span class="plain-syntax"> (</span><span class="identifier-syntax">id</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">DEBUG_CLSW:</span><span class="plain-syntax"> </span><span class="identifier-syntax">this_is_a_debug_compile</span><span class="plain-syntax"> = </span><span class="identifier-syntax">val</span><span class="plain-syntax">; </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">FORMAT_CLSW:</span><span class="plain-syntax"> </span><span class="identifier-syntax">output_format</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">RELEASE_CLSW:</span><span class="plain-syntax"> </span><span class="identifier-syntax">this_is_a_release_compile</span><span class="plain-syntax"> = </span><span class="identifier-syntax">val</span><span class="plain-syntax">; </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">NEST_CLSW:</span>
<span class="plain-syntax"> </span><a href="1-ic.html#SP12" class="function-link"><span class="function-syntax">Supervisor::add_nest</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Pathnames::from_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">), </span><span class="constant-syntax">GENERIC_NEST_TAG</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">INTERNAL_CLSW:</span>
<span class="plain-syntax"> </span><a href="1-ic.html#SP12" class="function-link"><span class="function-syntax">Supervisor::add_nest</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Pathnames::from_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">), </span><span class="constant-syntax">INTERNAL_NEST_TAG</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">EXTERNAL_CLSW:</span>
<span class="plain-syntax"> </span><a href="1-ic.html#SP12" class="function-link"><span class="function-syntax">Supervisor::add_nest</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">Pathnames::from_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">), </span><span class="constant-syntax">EXTERNAL_NEST_TAG</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">TRANSIENT_CLSW:</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">shared_transient_resources</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Pathnames::from_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">BASIC_CLSW:</span><span class="plain-syntax"> </span><a href="5-ps2.html#SP22" class="function-link"><span class="function-syntax">Projects::enter_forcible_basic_mode</span></a><span class="plain-syntax">(); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">KIT_CLSW:</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Errors::fatal</span><span class="plain-syntax">(</span><span class="string-syntax">"the -kit option has been withdrawn"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">PROJECT_CLSW:</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Pathnames::from_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="1-ic.html#SP18" class="function-link"><span class="function-syntax">Supervisor::set_I7_bundle</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">) == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Errors::fatal_with_text</span><span class="plain-syntax">(</span><span class="string-syntax">"can't specify the project twice: '%S'"</span><span class="plain-syntax">, </span><span class="identifier-syntax">arg</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">SOURCE_CLSW:</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Filenames::from_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="1-ic.html#SP17" class="function-link"><span class="function-syntax">Supervisor::set_I7_source</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">) == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Errors::fatal_with_text</span><span class="plain-syntax">(</span><span class="string-syntax">"can't specify the source file twice: '%S'"</span><span class="plain-syntax">, </span><span class="identifier-syntax">arg</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">O_CLSW:</span><span class="plain-syntax"> </span><span class="identifier-syntax">transpiled_output_file</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Filenames::from_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">CENSUS_CLSW:</span><span class="plain-syntax"> </span><span class="identifier-syntax">census_mode</span><span class="plain-syntax"> = </span><span class="identifier-syntax">val</span><span class="plain-syntax">; </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">PIPELINE_CLSW:</span><span class="plain-syntax"> </span><span class="identifier-syntax">inter_pipeline_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">PIPELINE_FILE_CLSW:</span><span class="plain-syntax"> </span><span class="identifier-syntax">inter_pipeline_file</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Filenames::from_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">PIPELINE_VARIABLE_CLSW:</span><span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="1-ic.html#SP7_1" class="named-paragraph-link"><span class="named-paragraph">Set a pipeline variable</span><span class="named-paragraph-number">7.1</span></a></span><span class="plain-syntax">; </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">RNG_CLSW:</span><span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="1-ic.html#SP7_2" class="named-paragraph-link"><span class="named-paragraph">Seed the random number generator</span><span class="named-paragraph-number">7.2</span></a></span><span class="plain-syntax">; </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">case</span><span class="plain-syntax"> </span><span class="identifier-syntax">CASE_CLSW:</span><span class="plain-syntax"> </span><span class="identifier-syntax">SourceLinks::set_case</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">); </span><span class="reserved-syntax">break</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP7_1" class="paragraph-anchor"></a><b>&#167;7.1. </b>Note that the following has no effect unless the <a href="../pipeline-module/index.html" class="internal">pipeline</a> module is part
of the parent. In practice, that will be true for <span class="extract"><span class="extract-syntax">inform7</span></span> but not <span class="extract"><span class="extract-syntax">inbuild</span></span>.
</p>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Set a pipeline variable</span><span class="named-paragraph-number">7.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">match_results</span><span class="plain-syntax"> </span><span class="identifier-syntax">mr</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Regexp::create_mr</span><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Regexp::match</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">, </span><span class="identifier-syntax">arg</span><span class="plain-syntax">, </span><span class="identifier-syntax">L</span><span class="string-syntax">"(%c+)=(%c+)"</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::get_first_char</span><span class="plain-syntax">(</span><span class="identifier-syntax">arg</span><span class="plain-syntax">) != </span><span class="character-syntax">'*'</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Errors::fatal</span><span class="plain-syntax">(</span><span class="string-syntax">"-variable names must begin with '*'"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">ifdef</span><span class="plain-syntax"> </span><span class="identifier-syntax">PIPELINE_MODULE</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Str::copy</span><span class="plain-syntax">(</span><span class="identifier-syntax">Dictionaries::create_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">pipeline_vars</span><span class="plain-syntax">, </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[0]), </span><span class="identifier-syntax">mr</span><span class="plain-syntax">.</span><span class="identifier-syntax">exp</span><span class="plain-syntax">[1]);</span>
<span class="plain-syntax"> #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Errors::fatal</span><span class="plain-syntax">(</span><span class="string-syntax">"-variable should take the form 'name=value'"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Regexp::dispose_of</span><span class="plain-syntax">(&amp;</span><span class="identifier-syntax">mr</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-ic.html#SP7">&#167;7</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP7_2" class="paragraph-anchor"></a><b>&#167;7.2. </b>16339 is a well-known prime number for use in 16-bit random number algorithms,
such as the one used in the Z-machine VM. It works fine in 32-bit cases too.
</p>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Seed the random number generator</span><span class="named-paragraph-number">7.2</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">val</span><span class="plain-syntax">) </span><span class="identifier-syntax">rng_seed_at_start_of_play</span><span class="plain-syntax"> = -16339;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">rng_seed_at_start_of_play</span><span class="plain-syntax"> = </span><span class="constant-syntax">0</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-ic.html#SP7">&#167;7</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;8. The Pretinkering, Tinkering, Nested and Projected phases. </b>Once the tool has finished with the command line, it should call this
function. Inbuild rapidly runs through the next few phases as it does so.
From the "nested" phase, the final list of nests in the search path for
finding kits, extensions and so on exists; from the "targeted" phase,
the main Inform project (if there is one) exists as a possible build target.
</p>
<p class="commentary">The parent should set <span class="extract"><span class="extract-syntax">compile_only</span></span> if it just wants to make a basic,
non-incremental compilation of any project. In practice, <span class="extract"><span class="extract-syntax">inform7</span></span> wants
that but <span class="extract"><span class="extract-syntax">inbuild</span></span> does not.
</p>
<p class="commentary">When this call returns to the parent, <span class="extract"><span class="extract-syntax">inbuild</span></span> is in the Targeted phase,
which continues until the parent calls <span class="extract"><span class="extract-syntax">Supervisor::go_operational</span></span> (see below).
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> (*</span><span class="identifier-syntax">shared_preform_callback</span><span class="plain-syntax">)(</span><span class="reserved-syntax">inform_language</span><span class="plain-syntax"> *);</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::optioneering_complete</span><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">compile_only</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> (*</span><span class="identifier-syntax">preform_callback</span><span class="plain-syntax">)(</span><span class="reserved-syntax">inform_language</span><span class="plain-syntax"> *)) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_IN_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">CONFIGURATION_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> = </span><span class="constant-syntax">PRETINKERING_INBUILD_PHASE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">shared_preform_callback</span><span class="plain-syntax"> = </span><span class="identifier-syntax">preform_callback</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="named-paragraph-container code-font"><a href="1-ic.html#SP8_1" class="named-paragraph-link"><span class="named-paragraph">Find the virtual machine</span><span class="named-paragraph-number">8.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="1-ic.html#SP19" class="function-link"><span class="function-syntax">Supervisor::make_project_from_command_line</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="1-ic.html#SP12" class="function-link"><span class="function-syntax">Supervisor::create_default_externals</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> = </span><span class="constant-syntax">TINKERING_INBUILD_PHASE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="1-ic.html#SP13" class="function-link"><span class="function-syntax">Supervisor::sort_nest_list</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> = </span><span class="constant-syntax">NESTED_INBUILD_PHASE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_project</span><span class="plain-syntax"> *</span><span class="identifier-syntax">proj</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER</span><span class="plain-syntax">(</span><span class="identifier-syntax">proj</span><span class="plain-syntax">, </span><span class="reserved-syntax">inform_project</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><a href="5-ps2.html#SP18" class="function-link"><span class="function-syntax">Projects::set_compilation_options</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">proj</span><span class="plain-syntax">,</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">this_is_a_release_compile</span><span class="plain-syntax">, </span><span class="identifier-syntax">compile_only</span><span class="plain-syntax">, </span><span class="identifier-syntax">rng_seed_at_start_of_play</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> = </span><span class="constant-syntax">TARGETED_INBUILD_PHASE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP8_1" class="paragraph-anchor"></a><b>&#167;8.1. </b>The VM to be used depends on the settings of all three of <span class="extract"><span class="extract-syntax">-format</span></span>,
<span class="extract"><span class="extract-syntax">-release</span></span> and <span class="extract"><span class="extract-syntax">-debug</span></span>, and those can be given in any order at the command
line, which is why we couldn't work this out earlier:
</p>
<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Find the virtual machine</span><span class="named-paragraph-number">8.1</span></span><span class="comment-syntax"> =</span>
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ext</span><span class="plain-syntax"> = </span><span class="identifier-syntax">output_format</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">with_debugging</span><span class="plain-syntax"> = </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">this_is_a_release_compile</span><span class="plain-syntax"> == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">this_is_a_debug_compile</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">with_debugging</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">ext</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">ext</span><span class="plain-syntax"> = </span><span class="identifier-syntax">I</span><span class="string-syntax">"Inform6"</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">target_vm</span><span class="plain-syntax"> *</span><span class="identifier-syntax">VM</span><span class="plain-syntax"> = </span><span class="identifier-syntax">TargetVMs::find_with_hint</span><span class="plain-syntax">(</span><span class="identifier-syntax">ext</span><span class="plain-syntax">, </span><span class="identifier-syntax">with_debugging</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="1-ic.html#SP9" class="function-link"><span class="function-syntax">Supervisor::set_current_vm</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">VM</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">VM</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">Errors::fatal</span><span class="plain-syntax">(</span><span class="string-syntax">"unrecognised compilation format"</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-ic.html#SP8">&#167;8</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>&#167;9. </b></p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">target_vm</span><span class="plain-syntax"> *</span><span class="identifier-syntax">current_target_VM</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">target_vm</span><span class="plain-syntax"> *</span><span class="function-syntax">Supervisor::current_vm</span><button class="popup" onclick="togglePopup('usagePopup4')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup4">Usage of <span class="code-font"><span class="function-syntax">Supervisor::current_vm</span></span>:<br/>Project Services - <a href="5-ps2.html#SP29">&#167;29</a>, <a href="5-ps2.html#SP31_1">&#167;31.1</a><br/>Headings - <a href="6-hdn.html#SP13">&#167;13</a><br/>Inclusions - <a href="6-inc.html#SP6_1">&#167;6.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_FROM_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">TINKERING_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">current_target_VM</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::set_current_vm</span><button class="popup" onclick="togglePopup('usagePopup5')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup5">Usage of <span class="code-font"><span class="function-syntax">Supervisor::set_current_vm</span></span>:<br/><a href="1-ic.html#SP8_1">&#167;8.1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">target_vm</span><span class="plain-syntax"> *</span><span class="identifier-syntax">VM</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_IN_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">PRETINKERING_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">current_target_VM</span><span class="plain-syntax"> = </span><span class="identifier-syntax">VM</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>&#167;10. The Graph Construction and Operational phases. </b><span class="extract"><span class="extract-syntax">inbuild</span></span> is now in the Targeted phase, then, meaning that the parent has
called <span class="extract"><span class="extract-syntax">Supervisor::optioneering_complete</span></span> and has been making further
preparations of its own. (For example, it could attach further kit
dependencies to the shared project.) The parent has one further duty to
perform: to call <span class="extract"><span class="extract-syntax">Supervisor::go_operational</span></span>. After that, everything is ready
for use.
</p>
<p class="commentary">The brief "graph construction" phase is used to build out dependency graphs.
We do that copy by copy.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::go_operational</span><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_IN_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">TARGETED_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> = </span><span class="constant-syntax">GRAPH_CONSTRUCTION_INBUILD_PHASE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><a href="2-cps.html#SP9" class="function-link"><span class="function-syntax">Copies::graph_everything</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">inbuild_phase</span><span class="plain-syntax"> = </span><span class="constant-syntax">OPERATIONAL_INBUILD_PHASE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">census_mode</span><span class="plain-syntax">) </span><a href="7-tm.html#SP2" class="function-link"><span class="function-syntax">ExtensionWebsite::handle_census_mode</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>&#167;11. The nest list. </b>Nests are directories which hold resources to be used by the Intools, and
one of Inbuild's main roles is to search and manage nests. All nests can
hold extensions, kits, language definitions, and so on.
</p>
<p class="commentary">But among nests three are special, and can hold other things as well.
</p>
<ul class="items"><li>(a) The "internal" nest is part of the installation of Inform as software.
It contains, for example, the build-in extensions. But it also contains
miscellaneous other files needed by Inform (see below).
</li><li>(b) The "external" nest is the one to which the user installs her own
selection of extensions, and so on. On most platforms, the external nest
is also the default home of "transient" storage, for more ephemeral content,
such as the mechanically generated extension documentation. Some mobile
operating systems are aggressive about wanting to delete ephemeral files
used by applications, so <span class="extract"><span class="extract-syntax">-transient</span></span> can be used to divert these.
</li><li>(c) Every project has its own private nest, in the form of its associated
Materials folder. For example, in <span class="extract"><span class="extract-syntax">Jane Eyre.inform</span></span> is a project, then
alongside it is <span class="extract"><span class="extract-syntax">Jane Eyre.materials</span></span> and this is a nest. The shared nest
list contains no Materials folders; each individual project has its own
search list of nests which contains its own Materials and then the shared
list from there on.
</li></ul>
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>&#167;12. </b>Inform customarily has exactly one <span class="extract"><span class="extract-syntax">-internal</span></span> and one <span class="extract"><span class="extract-syntax">-external</span></span> nest,
but in fact any number of each is allowed, including none. However, the
first to be declared are used by the compiler as "the" internal and external
nests, respectively.
</p>
<p class="commentary">The following hold the nests in declaration order.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">unsorted_nest_list</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="identifier-syntax">shared_internal_nest</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="identifier-syntax">shared_external_nest</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="function-syntax">Supervisor::add_nest</span><button class="popup" onclick="togglePopup('usagePopup6')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup6">Usage of <span class="code-font"><span class="function-syntax">Supervisor::add_nest</span></span>:<br/><a href="1-ic.html#SP7">&#167;7</a><br/>Project Services - <a href="5-ps2.html#SP2">&#167;2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">tag</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_BEFORE_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">TINKERING_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">unsorted_nest_list</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">unsorted_nest_list</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NEW_LINKED_LIST</span><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="identifier-syntax">N</span><span class="plain-syntax"> = </span><a href="2-nst.html#SP1" class="function-link"><span class="function-syntax">Nests::new</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="2-nst.html#SP2" class="function-link"><span class="function-syntax">Nests::set_tag</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="identifier-syntax">tag</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax">, </span><span class="identifier-syntax">unsorted_nest_list</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">tag</span><span class="plain-syntax"> == </span><span class="constant-syntax">EXTERNAL_NEST_TAG</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">shared_external_nest</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">shared_external_nest</span><span class="plain-syntax"> = </span><span class="identifier-syntax">N</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">tag</span><span class="plain-syntax"> == </span><span class="constant-syntax">INTERNAL_NEST_TAG</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">shared_internal_nest</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">shared_internal_nest</span><span class="plain-syntax"> = </span><span class="identifier-syntax">N</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">tag</span><span class="plain-syntax"> == </span><span class="constant-syntax">INTERNAL_NEST_TAG</span><span class="plain-syntax">) </span><a href="2-nst.html#SP3" class="function-link"><span class="function-syntax">Nests::protect</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">N</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::create_default_externals</span><button class="popup" onclick="togglePopup('usagePopup7')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup7">Usage of <span class="code-font"><span class="function-syntax">Supervisor::create_default_externals</span></span>:<br/><a href="1-ic.html#SP8">&#167;8</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_BEFORE_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">TINKERING_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><span class="identifier-syntax">shared_external_nest</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">E</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">home_path</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">char</span><span class="plain-syntax"> *</span><span class="identifier-syntax">subfolder_within</span><span class="plain-syntax"> = </span><span class="identifier-syntax">INFORM_FOLDER_RELATIVE_TO_HOME</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">subfolder_within</span><span class="plain-syntax">[0]) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">SF</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">SF</span><span class="plain-syntax">, </span><span class="string-syntax">"%s"</span><span class="plain-syntax">, </span><span class="identifier-syntax">subfolder_within</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Pathnames::down</span><span class="plain-syntax">(</span><span class="identifier-syntax">home_path</span><span class="plain-syntax">, </span><span class="identifier-syntax">SF</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">SF</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Pathnames::down</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">I</span><span class="string-syntax">"Inform"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">E</span><span class="plain-syntax"> = </span><a href="1-ic.html#SP12" class="function-link"><span class="function-syntax">Supervisor::add_nest</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="constant-syntax">EXTERNAL_NEST_TAG</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>&#167;13. </b>It is then sorted in tag order:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="identifier-syntax">shared_nest_list</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::sort_nest_list</span><button class="popup" onclick="togglePopup('usagePopup8')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup8">Usage of <span class="code-font"><span class="function-syntax">Supervisor::sort_nest_list</span></span>:<br/><a href="1-ic.html#SP8">&#167;8</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_IN_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">TINKERING_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">shared_nest_list</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NEW_LINKED_LIST</span><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="identifier-syntax">N</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax">, </span><span class="identifier-syntax">unsorted_nest_list</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="2-nst.html#SP2" class="function-link"><span class="function-syntax">Nests::get_tag</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">) == </span><span class="constant-syntax">MATERIALS_NEST_TAG</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax">, </span><span class="identifier-syntax">shared_nest_list</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax">, </span><span class="identifier-syntax">unsorted_nest_list</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="2-nst.html#SP2" class="function-link"><span class="function-syntax">Nests::get_tag</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">) == </span><span class="constant-syntax">EXTERNAL_NEST_TAG</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax">, </span><span class="identifier-syntax">shared_nest_list</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax">, </span><span class="identifier-syntax">unsorted_nest_list</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="2-nst.html#SP2" class="function-link"><span class="function-syntax">Nests::get_tag</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">) == </span><span class="constant-syntax">GENERIC_NEST_TAG</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax">, </span><span class="identifier-syntax">shared_nest_list</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">LOOP_OVER_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax">, </span><span class="identifier-syntax">unsorted_nest_list</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="2-nst.html#SP2" class="function-link"><span class="function-syntax">Nests::get_tag</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">) == </span><span class="constant-syntax">INTERNAL_NEST_TAG</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">ADD_TO_LINKED_LIST</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax">, </span><span class="identifier-syntax">shared_nest_list</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>&#167;14. </b>And the rest of Inform or Inbuild can now use:
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">linked_list</span><span class="plain-syntax"> *</span><span class="function-syntax">Supervisor::shared_nest_list</span><button class="popup" onclick="togglePopup('usagePopup9')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup9">Usage of <span class="code-font"><span class="function-syntax">Supervisor::shared_nest_list</span></span>:<br/>Incremental Building - <a href="3-ib.html#SP7">&#167;7</a><br/>Extension Services - <a href="5-es.html#SP7">&#167;7</a><br/>Project Services - <a href="5-ps2.html#SP7">&#167;7</a><br/>Dictionary - <a href="7-dct.html#SP9">&#167;9</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_FROM_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">NESTED_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">shared_nest_list</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"nest list never sorted"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">shared_nest_list</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="function-syntax">Supervisor::internal</span><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_FROM_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">NESTED_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">shared_internal_nest</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">inbuild_nest</span><span class="plain-syntax"> *</span><span class="function-syntax">Supervisor::external</span><button class="popup" onclick="togglePopup('usagePopup10')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup10">Usage of <span class="code-font"><span class="function-syntax">Supervisor::external</span></span>:<br/>Project Services - <a href="5-ps2.html#SP34_1">&#167;34.1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_FROM_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">NESTED_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">shared_external_nest</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>&#167;15. </b>This tells the <a href="../html-module/index.html" class="internal">html</a> module where to find, say, CSS files. Those files
are not managed by <a href="../inbuild/index.html" class="internal">inbuild</a>, have no versions, or anything fancy: they're
just plain old files.
</p>
<pre class="definitions code-font"><span class="definition-keyword">define</span> <span class="constant-syntax">INSTALLED_FILES_HTML_CALLBACK</span><span class="plain-syntax"> </span><a href="1-ic.html#SP15" class="function-link"><span class="function-syntax">Supervisor::installed_files</span></a>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="function-syntax">Supervisor::installed_files</span><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">shared_internal_nest</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">shared_internal_nest</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">location</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">Pathnames::from_text</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="string-syntax">"inform7/Internal"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP16" class="paragraph-anchor"></a><b>&#167;16. </b>As noted above, the transient area is used for ephemera such as dynamically
written documentation and telemetry files. <span class="extract"><span class="extract-syntax">-transient</span></span> sets it, but otherwise
the external nest is used.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="function-syntax">Supervisor::transient</span><button class="popup" onclick="togglePopup('usagePopup11')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup11">Usage of <span class="code-font"><span class="function-syntax">Supervisor::transient</span></span>:<br/>Project Services - <a href="5-ps2.html#SP6">&#167;6</a><br/>The Mini-Website - <a href="7-tm.html#SP3">&#167;3</a><br/>Dictionary - <a href="7-dct.html#SP1">&#167;1</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">void</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_FROM_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">TINKERING_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">shared_transient_resources</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">shared_external_nest</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">shared_external_nest</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">location</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">shared_transient_resources</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP17" class="paragraph-anchor"></a><b>&#167;17. The shared project. </b>In any single run, each of the Inform tools concerns itself with a single
Inform 7 program. This can be presented to it either in a project bundle
(a directory which contains source, settings, space for an index and for
temporary build files), or as a single file (just a text file containing
source text).
</p>
<p class="commentary">It is also possible o set a folder to be the project bundle, and nevertheless
specify a file somewhere else to be the source text. What you can't do is
specify the bundle twice, or specify the file twice.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">project_bundle_request</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">project_file_request</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::set_I7_source</span><button class="popup" onclick="togglePopup('usagePopup12')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup12">Usage of <span class="code-font"><span class="function-syntax">Supervisor::set_I7_source</span></span>:<br/><a href="1-ic.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_FROM_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">CONFIGURATION_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">project_file_request</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">project_file_request</span><span class="plain-syntax"> = </span><span class="identifier-syntax">F</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP18" class="paragraph-anchor"></a><b>&#167;18. </b>If we are given a <span class="extract"><span class="extract-syntax">-project</span></span> on the command line, we can then work out
where its Materials folder is, and therefore where any expert settings files
would be. Note that the name of the expert settings file depends on the name
of the parent, i.e., it will be <span class="extract"><span class="extract-syntax">inform7-settings.txt</span></span> or <span class="extract"><span class="extract-syntax">inbuild-settings.txt</span></span>
depending on who's asking.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::set_I7_bundle</span><button class="popup" onclick="togglePopup('usagePopup13')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup13">Usage of <span class="code-font"><span class="function-syntax">Supervisor::set_I7_bundle</span></span>:<br/><a href="1-ic.html#SP7">&#167;7</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_FROM_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">CONFIGURATION_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">project_bundle_request</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">project_bundle_request</span><span class="plain-syntax"> = </span><span class="identifier-syntax">P</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">materials</span><span class="plain-syntax"> = </span><a href="5-ps2.html#SP4" class="function-link"><span class="function-syntax">Projects::materialise_pathname</span></a><span class="plain-syntax">(</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">Pathnames::up</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">), </span><span class="identifier-syntax">Pathnames::directory_name</span><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">));</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">leaf</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">leaf</span><span class="plain-syntax">, </span><span class="string-syntax">"%s-settings.txt"</span><span class="plain-syntax">, </span><span class="identifier-syntax">PROGRAM_NAME</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">expert_settings</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Filenames::in</span><span class="plain-syntax">(</span><span class="identifier-syntax">materials</span><span class="plain-syntax">, </span><span class="identifier-syntax">leaf</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">TextFiles::exists</span><span class="plain-syntax">(</span><span class="identifier-syntax">expert_settings</span><span class="plain-syntax">))</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">CommandLine::also_read_file</span><span class="plain-syntax">(</span><span class="identifier-syntax">expert_settings</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">leaf</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">TRUE</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP19" class="paragraph-anchor"></a><b>&#167;19. </b>This is a deceptively simple-looking function, which took a lot of time
to get right. The situation is that the parent tool may already have
identified a copy <span class="extract"><span class="extract-syntax">C</span></span> to be the main Inform project of this run, or it may not.
If it has, we ignore <span class="extract"><span class="extract-syntax">-project</span></span> but apply <span class="extract"><span class="extract-syntax">-source</span></span> to change its source text
location. If it hasn't, we create a project using <span class="extract"><span class="extract-syntax">-project</span></span> if possible,
<span class="extract"><span class="extract-syntax">-source</span></span> if not, and in either case apply <span class="extract"><span class="extract-syntax">-source</span></span> to the result.
</p>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">Supervisor::make_project_from_command_line</span><button class="popup" onclick="togglePopup('usagePopup14')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup14">Usage of <span class="code-font"><span class="function-syntax">Supervisor::make_project_from_command_line</span></span>:<br/><a href="1-ic.html#SP8">&#167;8</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">inbuild_copy</span><span class="plain-syntax"> *</span><span class="identifier-syntax">C</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">RUN_ONLY_IN_PHASE</span><span class="plain-syntax">(</span><span class="constant-syntax">PRETINKERING_INBUILD_PHASE</span><span class="plain-syntax">)</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">filename</span><span class="plain-syntax"> *</span><span class="identifier-syntax">F</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">; </span><span class="comment-syntax"> result of </span><span class="extract"><span class="extract-syntax">-source</span></span><span class="comment-syntax"> at the command line</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">pathname</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">; </span><span class="comment-syntax"> result of </span><span class="extract"><span class="extract-syntax">-project</span></span><span class="comment-syntax"> at the command line</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">project_bundle_request</span><span class="plain-syntax">) </span><span class="identifier-syntax">P</span><span class="plain-syntax"> = </span><span class="identifier-syntax">project_bundle_request</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">project_file_request</span><span class="plain-syntax">) </span><span class="identifier-syntax">F</span><span class="plain-syntax"> = </span><span class="identifier-syntax">project_file_request</span><span class="plain-syntax">;</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">C</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><a href="4-pbm.html#SP3" class="function-link"><span class="function-syntax">ProjectBundleManager::claim_folder_as_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">C</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">Errors::fatal</span><span class="plain-syntax">(</span><span class="string-syntax">"No such Inform project directory"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">F</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="identifier-syntax">C</span><span class="plain-syntax"> = </span><a href="4-pfm.html#SP3" class="function-link"><span class="function-syntax">ProjectFileManager::claim_file_as_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">C</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">Errors::fatal</span><span class="plain-syntax">(</span><span class="string-syntax">"No such Inform source file"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">C</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">inform_project</span><span class="plain-syntax"> *</span><span class="identifier-syntax">proj</span><span class="plain-syntax"> = </span><a href="5-ps2.html#SP8" class="function-link"><span class="function-syntax">Projects::from_copy</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">C</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">proj</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"chosen project is not a project"</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">F</span><span class="plain-syntax">) {</span>
<span class="plain-syntax"> </span><a href="5-ps2.html#SP9" class="function-link"><span class="function-syntax">Projects::set_primary_source</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">proj</span><span class="plain-syntax">, </span><span class="identifier-syntax">F</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> </span><a href="5-ps2.html#SP29" class="function-link"><span class="function-syntax">Projects::set_primary_output</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">proj</span><span class="plain-syntax">, </span><span class="identifier-syntax">transpiled_output_file</span><span class="plain-syntax">);</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax"> }</span>
<span class="plain-syntax">}</span>
</pre>
<nav role="progress"><div class="progresscontainer">
<ul class="progressbar"><li class="progressprev"><a href="1-sm.html">&#10094;</a></li><li class="progresschapter"><a href="P-wtmd.html">P</a></li><li class="progresscurrentchapter">1</li><li class="progresssection"><a href="1-sm.html">sm</a></li><li class="progresscurrent">ic</li><li class="progresschapter"><a href="2-gnr.html">2</a></li><li class="progresschapter"><a href="3-bg.html">3</a></li><li class="progresschapter"><a href="4-em.html">4</a></li><li class="progresschapter"><a href="5-es.html">5</a></li><li class="progresschapter"><a href="6-st.html">6</a></li><li class="progresschapter"><a href="7-tm.html">7</a></li><li class="progressnext"><a href="2-gnr.html">&#10095;</a></li></ul></div>
</nav><!--End of weave-->
</main>
</body>
</html>
Reference in a new issue View git blame Copy permalink