(use-project-creator)=

# Generate SPL Example Project

## Download SPL Core

You can either install the SPL Core from the Python Package Index (PyPI)

```powershell
pip install spl-core
```

or clone the repository from GitHub and install its dependencies:

```powershell
git clone https://github.com/avengineers/spl-core
cd spl-core
.\\build.ps1 -install
```

SPL Core has a command-line interface called `please`.

```{note}
If you have cloned the SPL Core repository you find the `please` script in the `.venv/Scripts` directory.
```

Make sure the installation was successful by running the following command:

```powershell
please --help
```

## Initialize a new SPL Project

Generate the example project:

```powershell
please init --project-dir C:\\tmp\\MyProject
```

This will create a new SPL project in the directory `C:\\tmp\\MyProject`.

Before you can build the project, you need to install its dependencies.
Change to the project directory and run the following command:

```powershell
.\\build.ps1 -install
```

Now you can build the project:

```powershell
.\\build.ps1 -build
```

Select one of the variants to build, e.g., `EnglishVariant`.
The created executable can be found in the directory `build\\EnglishVariant\\prod\\my_main.exe`.

Run the executable in the terminal will output:

```powershell
Hello, World!
```

## Generated Project

### PowerShell Build Script

The `build.ps1` PowerShell script acts as a centralized tool to streamline several tasks related to the project, such as installing dependencies, running, and testing the project. It can be viewed as a build automation script that ensures consistency in development and deployment activities.

You can provide several parameters to customize the script's behavior:

* `install` : Install all dependencies required to build.
* `build` : Build the target.
* `clean` : Clean build, wipe out all build artifacts.
* `buildKit` : Build kit to be used.
* `target` : Target to be built.
* `variants` : Variants (of the product) to be built (List of strings, leave empty to be asked or "all" for automatic build of all variants)
* `filter` : filter for selftests; define in pytest syntax: <https://docs.pytest.org/en/6.2.x/usage.html>; e.g. "EnglishVariant or test_EnglishVariant.py"
* `ninjaArgs` : Additional build arguments for Ninja (e.g., "-d explain -d keepdepfile" for debugging purposes)
* `reconfigure` : Delete CMake cache and reconfigure.

The following is a flowchart describing the script's operation:

```{mermaid}
flowchart TD

    Start(Start Script)
    Install{Install?}
    Build{Build?}
    Clean{Clean?}
    HandleClean[Remove All Build Artifacts]
    End(End Script)
    PressKey[Press Any Key to Continue]

    CheckTargetSelftests{Target 'selftests'?}
    HandleSelfTests[Execute Selftests]
    HandleVariants[Detect Variants]
    CleanVariant{Clean?}
    HandleVariantClean[Remove Variant Build Artifacts]
    ReconfigureCheck{Reconfigure?}
    HandleReconfigure[Remove Variant CMake Files]
    CMakeConfigure[Configure & Generate CMake]
    CMakeBuild[Build with CMake]

    Start --> Install
    Install -->|Yes| Bootstrap(Invoke Bootstrap)

    subgraph "BOOTSTRAP"
        Bootstrap-->GitConfig(Git-Config)
    end
    GitConfig-->Build

    Install -->|No| Build
    Build -->|No| PressKey
    Build -->|Yes| CheckTargetSelftests

    subgraph "BUILD"
        CheckTargetSelftests -->|Yes| Clean
        Clean -->|Yes| HandleClean
        Clean -->|No| HandleSelfTests
        HandleClean --> HandleSelfTests
        CheckTargetSelftests -->|No| HandleVariants
        HandleVariants --> CleanVariant
        CleanVariant -->|Yes| HandleVariantClean
        CleanVariant -->|No| ReconfigureCheck
        HandleVariantClean --> ReconfigureCheck
        ReconfigureCheck -->|Yes| HandleReconfigure
        ReconfigureCheck -->|No| CMakeConfigure
        HandleReconfigure --> CMakeConfigure
        CMakeConfigure --> CMakeBuild
    end

    HandleSelfTests --> PressKey
    CMakeBuild --> PressKey
    PressKey --> End
```

### Python Dependencies

There are some SPL Core features which require additional Python packages (the list is not exhaustive):

* `kconfiglib` : used to generate the configuration header file (`autoconf.h`) from the Kconfig files.
* `hammocking` : used to generate the mockups for the unit tests.
* `sphinx` : used to generate the documentation.

These Python dependencies are defined in the `Pipfile` and will be automatically installed when running the `build.ps1` script with the `-install` parameter.
There will be a Python virtual environment created in the `.venv` directory.

### Build Tools Dependencies

The build tools dependencies (like CMake, Ninja, Compiler etc.) are defined in the `scoopfile.json` file and will be automatically installed when running the `build.ps1` script with the `-install` parameter.
The tools are installed in the user directory under `scoop`.

C:/Users/&lt;username&gt;/scoop/apps

```{note}
For more information about `scoop` and how to import dependencies from a `scoopfile.json` file, please refer to the [scoop documentation](https://github.com/ScoopInstaller/Scoop).
```