# Setup a new project

## Get the example project

For this example, we will use a code sample from the following open-source project: [here](https://github.com/wedolow/Codes-Samples).

You may retrieve it using any of these methods:

* Using the following command:

  ```bash
  git clone https://github.com/wedolow/Codes-Samples
  ```
* Downloading the latest version as a zip [here](https://github.com/wedolow/Codes-Samples/archive/refs/heads/main.zip) and unzipping it.

The code used in this example is contained in the subfolder `FFT-C`. This code implements a CPU-based Fast Fourier Transform algorithm, includes a Makefile to build it, and contains test cases to stimulate the algorithm.

{% hint style="info" %}
The code does **not** need to be able to build or run on your own system, as we will be using a Debian 11 Docker container for build, run, analysis and optimization, provided to you by WedoLow.
{% endhint %}

***

## Create a new project

{% stepper %}
{% step %}

### Open projects page and create a new project

Once logged in, you end up on the projects page.

![beLow projects page](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/Gha1FtowHZKTth5yfiKz/image)

Click on **Create a new project**.
{% endstep %}

{% step %}

### Enter project name and description

Enter a project name (for example: `FFT-C`), an optional description and click **Next**.

![Project name and description settings](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/mgUGbkmdjWfE6KNoehaa/image)
{% endstep %}

{% step %}

### Select project mode and version

Select **Copy the project** and enter a version name.

* In *Copy* mode, beLow works on a copy of your project.
* In *Local* mode, it works directly in the project's directory (only possible for projects that can build on your own system).

![Project mode and version settings](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/z2k3YGNe9GaoINmsGDpj/image)
{% endstep %}

{% step %}

### Select the source folder

Provide the root directory of your project by either:

* Clicking **Browse** and selecting the `FFT-C` directory, or
* Drag-and-dropping the `FFT-C` directory from your file explorer.

Click **Confirm and next**.

![Source directory selection](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/DgP9mN486BUsVrBr5jg0/image)
{% endstep %}
{% endstepper %}

***

## Target platform, analysis and execution setup

In each project setup, define two platforms:

* Build platform: the system where all build actions, analyses and optimizations occur.
* Target platform: the system where the compiled code executes.

Example: if cross-compiling on Windows for a Raspberry Pi:

* Build platform: Windows (x86\_64 Intel Skylake)
* Target platform: Linux (AARCH64 Cortex-A53 ARMv8)

In this `FFT-C` example, build and target platforms are the same: Debian 11 Linux on x86\_64.

Even if your PC is not Skylake, select Skylake as a representative generic x86\_64 architecture.

![Platform and analysis settings](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/z27D9TgYPuojNu3ACLLK/image)

On the platform selection page:

* Select "Linux System - Debian GNU/Linux 11 (bullseye) - x86\_64 - Intel skylake".
* Activate "Dynamic analysis (auto)" so beLow automatically manages dynamic traces and profiling.
* Activate "Restructuring optimizations" to enable search for additional code optimizations when beLow can build/execute the project in a closed loop.

Click **Confirm and next**.

***

### Run script setup

Decide whether the execution script runs on the build platform or on the target platform.

* If on the build platform, the script must send the compiled binary to the target, execute it, and retrieve profiling data.
* If on the target platform, a beLow runner must be present to run and retrieve profiling data.

In this example the build and target are the same, so either option works.

Our test bench is the binary `app_test.exe` at the project root. Configure the run script as follows:

* Script content:

```bash
./app_test.exe
```

* Script execution path: (project root — leave empty)
* Shell: Bash or Sh

Click **Confirm and next**.

![Run script settings](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/cydlLp2L6T6YZOal3Ygl/image)

***

### Target options

You may choose to install software/packages or inject environment variables on the target platform. For this example, no target additions are needed.

Click **Confirm and next**.

![Target options](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/nqm1LFXhzVnH7sPADybh/image)

***

## Build platform and build settings

![Build platform selection](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/rYSCEkAqikKO8QHBuEI6/image)

On this screen select the build platform. You may see two possible platforms:

* Linux System - Debian GNU/Linux 11 (bullseye) - x86\_64 - Any CPU (a Dockerized platform provided by beLow)
* Another platform corresponding to your own system

Select **Linux System - Debian GNU/Linux 11 (bullseye) - x86\_64 - Any CPU** and click **Confirm and next**.

***

### Build options — install required software

In build options, you need to install a package `check` required by the `FFT-C` build process.

* Unroll the "Software to install" section and wait while the package list loads (the first time the Debian 11 Docker image is downloaded/extracted — may take a few minutes).
* Use the search bar to find the `check` package and select it.
* Click **Confirm and next**.

![Build options](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/72tTJVRfV4czBmWugteD/image)

***

### Build scripts setup

Tell beLow how to build the project for the selected target.

* Configure section: leave blank (no configuration required).
* Clean section:
  * Script content:

    ```bash
    make clean
    ```
  * Script execution path: project root (leave empty)
  * Shell: Bash or Sh

A clean script is optional but can help beLow understand the compilation process and run operations from a clean state.

* Build section:
  * Script content:

    ```bash
    make app_test.exe
    ```
  * Script execution path: project root (leave empty)
  * Shell: Bash or Sh

Click **Confirm and next**.

![Build scripts setup](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/t0B67bG6BFYcvGmEx6Dr/image)

***

### Build platform build and run scripts (for restructuring optimizations)

Because "Restructuring optimizations" is activated, provide build scripts that run on the build platform and how to run the executable on the build platform.

In this example the build and target platforms are the same, so these scripts are identical to the previous ones.

* Configure: leave blank
* Clean:

  ```bash
  make clean
  ```
* Build:

  ```bash
  make app_test.exe
  ```
* Run:

  ```bash
  ./app_test.exe
  ```
* Script execution path: project root (leave empty)
* Shell: Bash or Sh

Click **Confirm and next**.

![Host build scripts](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/GubWJzIvZ5C8lj2RNizH/image)

***

## Build and exploration process

After setup, jobs are triggered to:

* Test your project build
* Attempt to understand your build actions
* Explore source code to identify functions and hierarchy

When the job finishes, you will see a table with the list of all project functions.

Select a top function that represents the highest level in the hierarchy to be analyzed/optimized. All functions called by this function (recursively) will be considered. Functions in independent graphs or upstream of the top function graph will not.

Click **View function tree** to inspect how functions relate (optional).

![Function tree](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/1Dzlry7XntRJf4SRRApA/image)

Close the graph when done.

In this example, select `app_exec` as the top function. The functions that call it are test bench setup functions that do not need optimization, and `app_exec` is the entry point for FFT function calls of interest.

![Top function selection](https://content.gitbook.com/content/RsAxaJ8tY0k2TfmHaCbZ/blobs/0GR5qSBQwRmyGRvmup3x/image)

Leave quality settings untouched in this example.

After a short post-processing job, your project setup is complete. Proceed to run an analysis as described in your workflow.