Vous êtes ici : Accueil / Tuto : install star-engine

Tuto : install star-engine

Tutorial : how to install star-engine.

# Star Engine

## Overview

The Star-Engine is a collection of C libraries and programs which provide
several functionalities to help in the development of Monte Carlo solvers.
[Monte Carlo](https://en.wikipedia.org/wiki/Monte_Carlo_method) techniques are
particularly well suited to handle complex models with high dimensionality,
heavily detailed 3D environments, multiple-interactions between several
multi-scale phenomenons, etc. The target users of the Star-Engine are thus
numerical simulation engineers and researchers that want to efficiently
simulate complex models that are difficult to address without compromise.

The main Star-Engine libraries are the Star-Sampling and the Star-3D libraries.
[Star-Sampling](https://gitlab.com/meso-star/star-sp.git) provides a set
of [Pseudo] Random Number Generators and random variates useful in the
development of Monte-Carlo solvers which heavily rely on distributions of
random variables. [Star-3D](https://gitlab.com/meso-star/star-3d.git) provides
functionalities to define a complex virtual environment composed of a set of 3D
geometries that can then be ray-traced and sampled both robustly and
efficiently. These functionalities are particularly well suited for solvers
that have to deal with arbitrary 3D shapes (e.g. radiative or diffusive random
walks).

To help in the development of efficient Monte-Carlo integrators dealing with
complex data, Star-Engine proposes the following optional "helper" libraries.
[Star-3DAW](https://gitlab.com/meso-star/star-3daw.git) and
[Star-3DSTL](https://gitlab.com/meso-star/star-3dstl.git) create Star-3D shapes
from geometries saved, respectively, in the [Alias Wavefront
.obj](https://en.wikipedia.org/wiki/Wavefront_.obj_file) and [STereo
Lithography](https://en.wikipedia.org/wiki/STL_(file_format)) file formats. The
[Star-MonteCarlo](https://gitlab.com/meso-star/star-mc.git) library simplifies
the development of efficient Monte-Carlo solvers by providing multi-threaded
integration of user defined integrands. Finally,
[Star-Renderer](https://gitlab.com/meso-star/star-rdr.git) is a minimalist
rendering library that displays geometries described through
[Star-3D](https://gitlab.com/meso-star/star-3d.git).

In addition of the aforementioned projects, additional libraries and
applications based on the Star-Engine framework can be optionally installed.
They illustrate how the Star-Engine is used to develop a large range of
applications ranging from rendering to electromagnetism. Refer to their
associated documentation for details on their purpose:

  * [Star-Display](https://gitlab.com/meso-star/star-display.git)
  * [Star-GebhartFactor] (https://gitlab.com/meso-star/star-gf.git)
  * [Schiff](https://gitlab.com/meso-star/schiff.git)

## Quick start

The Star-Engine is actually a [CMake](https://cmake.org) script that manages
which "Star projects" to install. On its execution, it builds and deploys the
selected projects as well as their dependencies. In addition of binaries,
libraries headers are also installed, providing the whole environment required
to develop "Star-Engine based" softwares.

### Pre-requisites

Star-Engine is compatible GNU/Linux as well as Microsoft Windows 7 and later.
Note that only 64-bits operating systems are supported. Star-Engine relies on
the [CMake](https://cmake.org) build system (at least in version 2.8.12) as well
as on the [git](https://git-scm.com) source control. Since several projects are
directly built from sources, a C and C++ compiler - compatible with the C99 and
C++11 standards - must also be installed on the system (e.g. [GNU Compiler
Collection](https://gcc.gnu.org) 4.7 or later).

### Install

Use git to clone the Star-Engine repository on the target machine. Then,
generate the CMake project from the `CMakeLists.txt` file stored in the `cmake`
directory (Refer to the [CMake documentation](https://cmake.org/documentation)
for further informations on CMake). At this step, one can use the CMake user
interface to configure the Star-Engine installation (e.g. list of projects to
deploy, install destination, etc.). Finally, build the resulting project.  On
build invocation, the Star-Engine downloads, potentially builds, and installs
the Star-Engine projects as well as their dependencies in the
`CMAKE_INSTALL_PREFIX` directory. By default, the install destination is the
`local` sub-directory of the Star-Engine.


On a GNU/Linux operating system this can be sum up to the following command
lines:

    ~ $ git clone https://gitlab.com/meso-star/star-engine.git
    ~ $ mkdir star-engine/build && cd star-engine/build
    ~/star-engine/build $ cmake ../cmake && make
    ~/star-engine/build $ ls -lR ../local | more


On a Microsoft Windows operating system, first ensure that the directories of
the git and the cmake programs are registered into the `path` environment
variable. Then open a command prompt and execute the commands below. Note that
the following example assumes that Visual Studio 2015 is installed on the
system:

    C:\Users\Meso-Star>git clone https://gitlab.com/meso-star/star-engine.git
    C:\Users\Meso-Star>mkdir star-engine\build && cd star-engine\build
    C:\Users\Meso-Star\star-engine\build>cmake ..\cmake -G "Visual Studio 14 2015 Win64"
    C:\Users\Meso-Star\star-engine\build>cmake --build . --config Release
    C:\Users\Meso-Star\star-engine\build>dir /S ..\local | more

### Update

To update the overall Star-Engine framework, first check that the Star-Engine
repository is up to date. Then force its rebuild to update the outdated
projects.


On GNU/Linux:

    ~/star-engine/build $ git pull origin master
    ~/star-engine/build $ make clean && make

On Microsoft Windows:

    C:\Users\Meso-Star\star-engine\build>git pull origin master
    C:\Users\Meso-Star\star-engine\build>cmake --build . --config Release --target clean
    C:\Users\Meso-Star\star-enigne\build>cmake --build . --config Release


## Develop with the Star-Engine & CMake

Once installed, the Star-Engine provides [CMake
packages](https://cmake.org/cmake/help/v3.5/manual/cmake-packages.7.html) 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
directory to the CMake search paths. Then use the CMake package mechanism to
use the required Star-Engine libraries.

For instance, let a project relying on the
[Star-3D](https://gitlab.com/meso-star/star-3d.git) and the
[Star-SamPling](https://gitlab.com/meso-star/star-sp.git) libraries, with a
single source file `main.c` and a `CMakeLists.txt` file defined as follow:

    project(my_project C)

    # Use CMake packages to check and add project dependencies
    find_package(Star3D REQUIRED)
    find_package(StarSP REQUIRED)
    include_directories(${Star3D_INCLUDE_DIR} ${StarSP_INCLUDE_DIR})

    # Define the program to build
    add_executable(my_program main.c)

    # Link the program against the Star-Engine libraries on which it depends
    target_link_libraries(my_program StarSP Star3D)

On a GNU/Linux system, one can generate an Unix Makefile of this project
with the following command:

    cmake -G "Unix Makefiles" -DCMAKE_PREFIX_PATH="<STAR_ENGINE_DIR>" <MY_PROJECT_DIR>

On a Microsoft Windows operating system, first ensure that the directory of the
cmake program is registered into the `path` environment variable. Then execute
the following command to generate a Visual Studio 2015 solution of this
project:

    cmake -G "Visual Studio 14 2015 Win64" -DCMAKE_PREFIX_PATH="<STAR_ENGINE_DIR>" <MY_PROJECT_DIR>

with `<STAR_ENGINE_DIR>` the install location of the Star-Engine and
`<MY_PROJECT_DIR>` the directory where the aforementioned `CMakeLists.txt` file
is stored.

## License

Star Engine is copyright (C) |Meso|Star> 2015-2017 (<contact@meso-star.com>).
It is a free software released under the [OSI](http://opensource.org)-approved
CeCILL license. You are welcome to redistribute it under certain conditions;
refer to the COPYING files for details.