commit d062a1e0e5f879d5755acb76cdd5c9b0402cd1e2
parent 49a5873cd2529608ff3361e6ad790126a42d3ead
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Wed, 6 Dec 2017 10:48:16 +0100
Update the Quick start part of the Star-Engine
Diffstat:
| M | star-engine.html.in | | | 84 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------- |
1 file changed, 67 insertions(+), 17 deletions(-)
diff --git a/star-engine.html.in b/star-engine.html.in
@@ -28,7 +28,7 @@ to be taken into account or if additional <b>coupled phenomena</b> have to be
considered.
<p>Such complex situations are easily handled on the paper: physicists will
-essentially translate the physical integral they need to solve into a
+essentially translate the <b>physical integral</b> they need to solve into a
mathematical form that can be interpreted in terms of a Monte-Carlo algorithm.
But then, developing the associated simulation code might be very difficult, if
even possible, because mathematical expressions care little about data
@@ -45,9 +45,9 @@ order to evaluate the solution.</p>
<h2>Parts of the Star-Engine</h2>
-<p>The Star-Engine is actually a collection of <b>C libraries</b> available for
-x86-64 architectures on GNU/Linux as well as Microsoft Windows 7 and later.
-They are <b>free software</b> released under <a
+<p>The Star-Engine is a collection of <b>C libraries</b> available for x86-64
+architectures on GNU/Linux as well as Microsoft Windows 7 and later. They are
+<b>free software</b> released under <a
href=https://en.wikipedia.org/wiki/Copyleft>copyleft</a> licences. You are
welcome to redistribute them under certain conditions. Refer to their
associated licence for details.</p>
@@ -78,8 +78,8 @@ are briefly described below:</p>
</li><li>
<a
href="https://gitlab.com/meso-star/star-3dstl.git">Star-3DUtilityToolkit</a>
- provides functions to generate the triangular mesh of shapes as, for
- instance, cylinder, sphere or supershapes.
+ provides functions to generate the triangular mesh of several shapes like,
+ cylinder, sphere, supershapes <i>etc.</i>
</li><li>
<a href="https://gitlab.com/meso-star/star-3daw.git">Star-3DAW</a>
and <a href="https://gitlab.com/meso-star/star-3dstl.git">Star-3DSTL</a>
@@ -92,13 +92,14 @@ are briefly described below:</p>
<h2>Related projects</h2>
<p>The following software make use of the Star-Engine framework to implement
-Monte Carlo solvers for a wide range of purposes. Refer to the their associated
+Monte-Carlo solvers for a wide range of purposes. Refer to the their associated
documentation for more informations.</p>
<ul>
<li><a href="schiff.html">Schiff</a>: computes the radiative properties of
soft particles,</li>
- <li><a href="solstice.html">Solstice</a>: simulates concentrated solar plants,</li>
+ <li><a href="solstice.html">Solstice</a>: simulates concentrated solar
+ plants,</li>
<li><a href="stardis.html">Stardis</a>: solves coupled thermal problems,</li>
<li><a href="https://gitlab.com/meso-star/star-4v_s.git">Star-4V/S</a>:
evaluates an invariant property of diffuse random walks,</li>
@@ -116,10 +117,58 @@ libraries. Refer the Star-Engine <a
href="https://gitlab.com/meso-star/star-engine">git repository</a> for a
complete description of the procedure.</p>
-<p>Once installed, the Star-Engine provides CMake packages that help
-programmers to use its libraries in their softwares relying on the CMake
-build-system. To use these packages, at the CMake configuration step of the
-software, add the Star-Engine CMake package location as well as its install
+<p>On both cases, once installed, the structure of the Star-Engine directory
+looks like a regular Unix filesystem hierarchy:</p>
+
+<ul>
+ <li>The <code>bin</code> directory stands for binary and contains the
+ programs deployed with the Star-Engine.</li>
+ <li><code>etc</code> stores configuration files. Its name stands for
+ <i>etcetera</i>. For instance, on GNU/Linux it contains the
+ <code>star-engine.profile</code> bash script that, once "sourced", setup the
+ environment of the current shell for the development of Star-Engine based
+ applications.</li>
+ <li>The <code>include</code> directory contains the header files of the
+ 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>
+</ul>
+
+<h3>Raw compilation</h3>
+
+<p>Let 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 to 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
+</pre>
+
+<p>with <code><STAR_ENGINE_DIR></code> the install directory of the
+Star-Engine. 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>
+
+<pre class="code">
+$ gcc main.c -lssp
+</pre>
+
+<p>with <code>ssp</code> the name the <b>S</b>tar-<b>S</b>am<b>P</b>ling
+library in the <code><STAR_ENGINE_DIR>/lib</code> directory.</p>
+
+<p>Note that this procedure is practical for simple applications only. 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>
+
+<h3>CMake build-system</h3>
+
+<p>Star-Engine provides CMake packages that help programmers to use its
+libraries in their software relying on the CMake build system. To use these
+packages, at the CMake configuration step, add the Star-Engine install
directory to the CMake search paths. Then use the CMake package mechanism to
use the required Star-Engine libraries.</p>
@@ -148,8 +197,9 @@ target_link_libraries(my_program StarSP Star3D)
cmake -G<CMAKE_GENERATOR> -DCMAKE_PREFIX_PATH=<STAR_ENGINE_DIR> <MY_PROJECT_DIR>
</pre>
-<p>with <code><CMAKE_GENERATOR></code> the build system to use as for
-instance <code>"Unix Makefiles"</code>, <code><STAR_ENGINE_DIR></code>
-the install location of the Star-Engine and <code><MY_PROJECT_DIR></code>
-the directory where the aforementioned <code>CMakeLists.txt</code> file is
-stored.</p>
+<p>with <code><CMAKE_GENERATOR></code> the host build system to use as
+for instance <code>"Unix Makefiles"</code>,
+<code><STAR_ENGINE_DIR></code> the install location of the Star-Engine
+and <code><MY_PROJECT_DIR></code> the directory where the aforementioned
+<code>CMakeLists.txt</code> file is stored.</p>
+
