Skip to content
Snippets Groups Projects
Commit 1b8de266 authored by Eric Vidal's avatar Eric Vidal :speech_balloon:
Browse files

draft of module explanation

parent 6d0a9c76
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 144 additions and 5 deletions
doc/html/frontend.html
+ 144
− 5
View file @ 1b8de266
......@@ -16,7 +16,7 @@
<h1>The frontend service file</h1>
<p>
The <a href="https://skarnet.org/software/s6">s6</a> and <a href="https://skarnet.org/software/s6">s6-rc</a> programs each handle and use several kinds of services and different files. It is quite complex to understand and manage the relationship between all those files and services. If you're interested in the details you should read <a href="https://skarnet.org/software/s6/servicedir.html">the documentation for the s6 servicedir</a> and also about <a href="https://skarnet.org/software/s6/servicedir.html"><em>classic</em></a>, <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html"> <em>oneshot</em>, <em>longrun</em> (also called <em>atomic</em> services) and <em>bundle</em> services</a> on Obarun. The frontend service file of 66 tools allows you to deal with all these different services in a centralized manner in one single place.
The <a href="https://skarnet.org/software/s6">s6</a> and <a href="https://skarnet.org/software/s6">s6-rc</a> programs each handle and use several kinds of services and different files. It is quite complex to understand and manage the relationship between all those files and services. If you're interested in the details you should read <a href="https://skarnet.org/software/s6/servicedir.html">the documentation for the s6 servicedir</a> and also about <a href="https://skarnet.org/software/s6/servicedir.html"><em>classic</em></a>, <a href="https://skarnet.org/software/s6-rc/s6-rc-compile.html"> <em>oneshot</em>, <em>longrun</em> (also called <em>atomic</em> services), <em>bundle</em></a> and <em>module</em> services on Obarun. The frontend service file of 66 tools allows you to deal with all these different services in a centralized manner in one single place.
<br>
By default 66 tools expects to find any service files in <tt>%%service_system%%</tt> although this can be changed at compile time by passing the <tt>--with-service-path=<em>DIR</em></tt> option to <tt>./configure.</tt>
</p>
......@@ -89,6 +89,9 @@
<li>
<a href="#environment">[environment]</a>
</li>
<li>
<a href="#regex">[regex]</a>
</li>
</ul>
<p>
......@@ -204,6 +207,25 @@ long/path</pre>
<ul>
<pre>MYKEY=
MYVALUE</pre>
</ul>
<br><hr><br>
<li>
<tt><b>colon</b></tt> : A value between double colons followed by a <tt>pair</tt> syntax.
Must be one by line.
</li>
<p>Valid syntax:</p>
<ul>
<pre>::key=value</pre>
<pre>:filename:key=value</pre>
</ul>
<p>(!) Invalid syntax:</p>
<ul>
<pre>::MYKEY=
MYVALUE</pre>
<pre>::
MYKEY=MYVALUE</pre>
<pre>::key=value :filename:anotherkey=anothervalue</pre>
</ul>
</ul>
<br>
......@@ -837,6 +859,89 @@ created by default at %%service_admconf%%/name_of_service directory. The default
</ul>
</ul>
<br><hr>
<h2 id="regex">Section: [regex]</h2>
<p>This section is <em>optional</em>.</p>
<p>It will only have an effect when the service is a <tt><a href="#module">module</a></tt> type.</p>
<p>You can use the '@I' string as key field. It will replaced by the
<tt><a href="#module">module</a></tt> name as you do for instantiated service before applying the
regex section.</p>
<h3>Valid <em>key</em> names:</h3>
<ul>
<li><h4>@configure</h4></li>
<h5>Without equivalent, this key is unique to 66 tools.</h5>
<p><tt>mandatory</tt> : no</p>
<p><tt>syntax</tt> : quotes</p>
<p><tt>valid value</tt> :</p>
<ul>
<p>You can define any arguments to pass to the module's configure script.</p>
</ul>
<hr style="border: 1px dashed #000000">
<li><h4>@directories</h4></li>
<h5>Without equivalent, this key is unique to 66 tools.</h5>
<p><tt>mandatory</tt> : no</p>
<p><tt>syntax</tt> : pair inside bracket</p>
<p><tt>valid value</tt> :</p>
<ul>
<p>Any key=value pair where key is the regex to search on the
directory name and value the replacement of that regex. For example:</p>
<pre>
@directories = ( DM=sddm TRACKER=consolekit )
</pre>
<p>Where the module directory contains two sub-directories named use-DM and by-TRACKER directories. Its will be renamed as use-sddm and
by-consolekit respectively.</p>
</ul>
<hr style="border: 1px dashed #000000">
<li><h4>@files</h4></li>
<h5>Without equivalent, this key is unique to 66 tools.</h5>
<p><tt>mandatory</tt> : no</p>
<p><tt>syntax</tt> : pair inside bracket</p>
<p><tt>valid value</tt> :</p>
<ul>
<p>Reacts exactly as @directories field but on filename instead of
directories name.</p>
</ul>
<hr style="border: 1px dashed #000000">
<li><h4>@infiles</h4></li>
<h5>Without equivalent, this key is unique to 66 tools.</h5>
<p><tt>mandatory</tt> : no</p>
<p><tt>syntax</tt> : colon</p>
<p><tt>valid value</tt> :</p>
<ul>
<p>Any valid filename between the double colon with any key=value pair where
key is the regex to search inside the file and value the replacement
of that regex. The double colon <b>must</b> be present but the name between it
can be omitted. In that case, the key=value pair will be apply to
all files contained on the module directories and to all key (regex)
found inside the same file.For example:</p>
<pre>
@infiles = ( :mount-tmp:args=-o noexec
::user=@I )
</pre>
<li>
It replaces first the term @I by the name of the module.
</li>
<li>
It opens the file named mount-tmp, search for the args regex
and replace it by the value of the regex.
</li>
<li>
It opens all files found on the module directory and replace
all regex 'user' found by the name of the module in each file.
</li>
</ul>
</ul>
<br><hr>
<h2>A word about the @execute key</h2>
......@@ -891,7 +996,7 @@ for it in your <tt>@execute</tt> field.</p>
<br><hr>
<h2 id="instance">Instance service file creation</h2>
<h2 id="instance">Instantiated service file creation</h2>
<p>An <em>instance</em> service file is of the same syntax as
decribed in this document for any other service. It can be any <em>type</em>
of service. However some differences exist :
......@@ -923,12 +1028,40 @@ for it in your <tt>@execute</tt> field.</p>
@build = auto
@execute = ( agetty -J 38400 tty1 } )</pre>
</p>
<br><hr>
<br><hr>
<h2 id="module">Module service file creation</h2>
<p>A module can be considered as an <tt><a href="#instance">instantiated</a></tt>
service. It works as the same way concerning the frontend file but
allow to configure a set of differents kind of services before executing
the enable process. Also, the set of the services can be configured
with the conjonction of a script called <tt>configure</tt> which it can be
made on any language.</p>
<p>A module is define with two elements: an instantiated frontend service
file at %%service_system%% and a directory at %%service_module%%.
The name of the frontend and the directory <b>must</b> be the same.
For example if the frontend is named foo@, the directory of the module
must be foo@.</p>
<p>The module directory can contain a sub-directory named <tt>.configure</tt>
with an <b>executable</b> file script named <tt>configure</tt> inside. For example,
foo@/.configure/configure. The sub-directory <b>must</b> be named
<tt>.configure</tt> and the file scripts <b>must</b> be named <tt>configure</tt>.</p>
<p>It's up to you to write the <tt>configure</tt> script file with the
language of your choice as long as you define a correct <tt>shebang</tt>.</p>
<p>The <tt>configure</tt> script is launched after the parse of the
frontend file meaning all regex on directories and files is already made.</p>
<br><hr>
<h2 id="proto">Prototype of a frontend file</h2>
<p>This prototype contain all valid <em>section</em> with all valid <em>key=value</em> pair.</p>
<pre>
[main]
@type = classic,bundle,longrun,oneshot
@type = classic,bundle,longrun,oneshot,module
@name =
@description = ""
@depends = ()
......@@ -973,6 +1106,12 @@ for it in your <tt>@execute</tt> field.</p>
[environment]
MYKEY=myvalue
ANOTHERKEY=!antohervalue
ANOTHERKEY=!antohervalue
[regex]
@configure="arguments to pass to configure script"
@directories=(key=value)
@files=(key=value)
@infiles=(:filename:key=value ::key=value)
</pre>
</body></html>
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment