commit 4c0bebcbe92fbcc3a271eb547d0afde08758135c
parent 908a8a3026d63db11cd542f6508567e5c8ffa7eb
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Thu, 17 Jun 2021 14:15:47 +0200
Update the Star-Engine overview
Diffstat:
1 file changed, 56 insertions(+), 27 deletions(-)
diff --git a/star-engine/star-engine.html.in b/star-engine/star-engine.html.in
@@ -66,22 +66,42 @@ documentation for more informations.</p>
factor</a> between 3D primitives.</li>
</ul>
-<h2>Quick start</h2>
+<h2>Install</h2>
+
+<p>Although we can install and use each of the components of the Star-Engine
+separately, the easiest way is to deploy them as they are packaged in a
+specific version of the Star-Engine which guarantees their reciprocal
+compatibility.</p>
-<p> While one can install and use each component separately, the canonical way
-is to deploy them through a <a href="star-engine-downloads.html">specific
-version</a> of the Star-Engine that packages the different libraries to ensure
-their reciprocal compatibilities.</p>
+<p>One way to install the Star-Engine is to <a
+href="star-engine-downloads.html">download</a> a <b>pre-compiled</b> version
+and check its integrity against its <a href=../misc/pgp_signatures.html>PGP
+signature</a> before extracting it.
-<p>Download the desired Star-Engine binary archive and check its integrity
-against its <a href=../misc/pgp_signatures.html>PGP signature</a>. Then extract it.
-You can alternatively install Star-Engine directly from source. Visit the
-Star-Engine <a
-href="https://gitlab.com/meso-star/star-engine">git repository</a> for a
-complete description of the procedure.</p>
+<p>You can alternatively <b>compile</b> the Star-Engine directly from its
+sources. On GNU/Linux, first make sure that you have installed <a
+href=https://git-scm.com>git</a>, <a href="https://cmake.org">CMake</a> 3.1 or
+higher and <a href=https://gcc.gnu.org>GNU Compiler Colection</a> 4.8 or
+higher. Then, in a GNU/Bash shell, type the following commands:</p>
-<p>Once installed, the directory of Star-Engine looks like a regular Unix
-filesystem hierarchy:</p>
+<pre class="code">
+~ $ git clone -b ${VERSION} \
+ https://gitlab.com/meso-star/star-engine.git \
+ Star-Engine-${VERSION}
+~ $ mkdir Star-Engine-${VERSION}/build
+~ $ cd Star-Engine-${VERSION}/build
+~/Star-Engine-${VERSION}/build $ cmake ../cmake
+~/Star-Engine-${VERSION}/build $ make
+</pre>
+
+<p>These commands install the Star-Engine at the root of your home directory in
+the <code>Star-Engine-${VERSION}/local</code> sub-directory. Visit the
+Star-Engine <a href="https://gitlab.com/meso-star/star-engine">git
+repository</a> for a complete description of the build process and available
+options.</p>
+
+<p>Once installed, the directory in which the Star-Engine is deployed looks
+like a classic Unix file system hierarchy:</p>
<ul>
<li>The <code>bin</code> directory stands for binary and contains the
@@ -95,25 +115,32 @@ filesystem hierarchy:</p>
Star-Engine libraries. Theses files should be included in your C/C++
application through the <code>#include</code> directive.</li>
<li>The <code>lib</code> directory stores the Star-Engine libraries.</li>
- <li>The <code>share</code> directory contains architecture independent data,
- like the licenses of the installed software.</li>
+ <li>Finally, the <code>share</code> directory contains architecture
+ independent data, like the licenses of the installed libraries.</li>
</ul>
-<h3>Raw compilation</h3>
+<h2>Quick start</h2>
-<p>Consider a GNU/Linux environment and a project with a single source file
-named <code>main.c</code> that uses Star-SamPling to generate random numbers.
-To build the project executable, one has first to register the Star-Engine
-installation in the current shell by sourcing its "profile".</p>
+<p>Once the Star-Engine is deployed, you can develop C/C++ applications using
+its libraries. Consider a GNU/Linux environment and a project with a single
+source file named <code>main.c</code> that uses the Star-Engine's<a
+href=https://gitlab.com/meso-star/star-sp.git>Star-SamPling library</a> to
+generate random numbers. To build the project executable, you must first
+register the Star-Engine installation in the current shell by sourcing its
+"profile".</p>
<pre class="code">
-$ source <STAR_ENGINE_DIR>/etc/star-engine.profile
+~ $ source <STAR_ENGINE_DIR>/etc/star-engine.profile
</pre>
<p>where <code><STAR_ENGINE_DIR></code> is the Star-Engine install
-directory. Once done, assuming that <b>G</b>NU <b>C</b>ompiler
-<b>C</b>ollection is installed on the system, one can compile the program with
-a regular <code>gcc</code> invocation.</p>
+directory. This script updates the environment variables of the current shell
+with the install information of the Star-Engine. The updated environment
+variables are: <code>LD_LIBRARY_PATH</code>, <code>PATH</code>,
+<code>MANPATH</code>, <code>CPATH</code> and <code>LIBRARY_PATH</code>. Once
+this is done, assuming that <b>G</b>NU <b>C</b>ompiler <b>C</b>ollection is
+installed on the system, one can compile the program with a common invocation
+of <code>gcc</code>.</p>
<pre class="code">
$ gcc main.c -lssp
@@ -125,7 +152,7 @@ library in the <code><STAR_ENGINE_DIR>/lib</code> directory.</p>
<p>Note that this procedure is only practical for simple projects. For more
advanced software one should rely on a build system like <a
href="https://www.gnu.org/software/make/">GNU Make</a> or <a
-href="https://cmake.org/">CMake</a>.</p>
+href="https://cmake.org/">CMake</a> (see below).</p>
<h3>CMake build system</h3>
@@ -135,8 +162,10 @@ their software. In order to use these packages, add the Star-Engine install
directory to the CMake search paths at the CMake configuration step. Then use
the CMake package mechanism to use the required Star-Engine libraries.</p>
-<p>For instance, consider a project relying on the Star-3D and the
-Star-SamPling libraries, with a single source file <code>main.c</code> and a
+<p>For instance, consider a project relying on the <a
+href=https://gitlab.com/meso-star/star-3d.git>Star-3D</a> and the <a
+href=https://gitlab.com/meso-star/star-sp.git>Star-SamPling</a> libraries of
+the Star-Engine, with a single source file <code>main.c</code> and a
<code>CMakeLists.txt</code> file defined as follow:</p>
<pre class="code">
