# Running Adaptyst<no value>
## Starting performance analysis
After [you set up modules and define your computer system](/docs/adaptyst/system-graphs), you can analyse your first program!

At the moment, Adaptyst supports commands only for performance analysis (more workflow types are coming soon). To analyse your program, please run the following command:
```bash
adaptyst -s <path to your system def file> -d <command to be run and analysed>
```

{{< callout context="caution" title="Important" icon="outline/alert-triangle" >}}
* If your command has whitespaces, you must run Adaptyst in one of these ways:
```adaptyst -s <path to your system def file> -d "<command to be run and analysed>"```
or ```adaptyst -s <path to your system def file> -d -- <command to be run and analysed>```.
* If your command uses any shell-specific syntax (e.g. redirection using ```<``` or ```>```), you need
to pass it through your shell as Adaptyst uses direct system calls to run programs. For example, to
analyse ```program123 < test.txt``` run through bash, you need to execute
```adaptyst -s <path to your system def file> -d -- /bin/bash -c "program123 < test.txt"```.
{{< /callout >}}

{{< callout context="caution" title="Permissions required to run Adaptyst" icon="outline/alert-triangle" >}}
Depending on the modules used, Adaptyst may need to be run as root or with specific permission setup
steps performed beforehand. See the documentation of your modules for more information.
{{< /callout >}}

If you want to see what extra options you can set, run ```adaptyst --help```.
{{< details "Help message printed by ```adaptyst --help```" >}}
```
Adaptyst: a performance analysis tool 


adaptyst [OPTIONS] [COMMAND/PATH...]


POSITIONALS:
  COMMAND/PATH                     Path to a workflow to be analysed 
                                   (required). If -d is set, a command to be 
                                   analysed should be provided instead. 
                                   

OPTIONS:
  -h,      --help                  Print this help message and exit 
  -v,      --version               Display program version information and exit 
           --modules               List in detail all installed system modules 
                                   and exit 
                                   
           --plugins               List in detail all installed workflow 
                                   plugins and exit 
                                   
           --info                  Print information about various paths used 
                                   by Adaptyst such as the module dir(s) 
                                   
  -m,      --module-help MODULE    Print the help message of a given module 
                                   and exit 
                                   
  -p,      --plugin-help PLUGIN    Print the help message of a given plugin 
                                   and exit 
                                   
  -d,      --command               Indicates that a command will be provided 
                                   for analysis rather than the path to a YAML 
                                   file defining a workflow to be analysed 
                                   
  -s,      --system FILE           Path to the definition file of a computer 
                                   system (required). See the documentation to 
                                   learn how to write a computer system 
                                   definition file. 
                                   
  -o,      --output PATH           Path to the directory where analysis 
                                   results should be saved (default: 
                                   adaptyst_<UTC timestamp>__<positive 
                                   integer>) 
                                   
  -l,      --label TEXT            Label of the performance analysis session 
                                   (default: adaptyst_<UTC 
                                   timestamp>__<positive integer>) 
                                   
           --buffer UINT           Size of buffer for internal communication 
                                   in bytes (default: 1024) 
                                   
           --no-format             Do not use any non-standard terminal 
                                   formatting 
                                   

If you want to change the paths of the system-wide and local Adaptyst 
configuration files, set the environment variables ADAPTYST_CONFIG and 
ADAPTYST_LOCAL_CONFIG respectively to values of your choice. Similarly, 
you can set the ADAPTYST_MODULE_DIRS environment variable to change the 
colon-separated paths where Adaptyst looks for workflow plugins and system 
modules. You can also set ADAPTYST_MISC_DIR to change the path where Adaptyst 
looks for its support files.
```
{{< /details >}}

After performance analysis is completed, you can check the results inside ```adaptyst_<UTC timestamp>__<positive integer>``` (e.g. ```adaptyst_2025_08_12_13_05_43__1```) unless you have
set the -o option (then you can check the folder you have specified via -o).

You can run ```adaptyst``` multiple times, all performance analysis results will be saved in separate folders inside the same working directory provided that you haven't set the -o option.

{{< details "Structure of results" >}}
* **log**: Logs produced by Adaptyst and entities/nodes/modules, structured into entities -> nodes -> modules. Additional files are provided below.
  * **\<entity\>\_stdout.log**: stdout of a user workflow in case it has been run in an entity.
  * **\<entity\>\_stderr.log**: stderr of a user workflow in case it has been run in an entity.
* **system**: Results produced by entities/nodes/modules, structured into entities -> nodes -> modules. The structure inside modules is module-dependent. Additional files are provided below.
  * **system.yml**: The copy of a system definition file.
  * **\<entity\>/src.zip**: Detected source code files of a user workflow within an entity.
  * **\<entity\>/dirmeta.json**: User workflow execution metadata such as its exit code in case the workflow has been run in an entity. This file is optional.
* **dirmeta.json**: Session metadata such as its date and time.
{{< /details >}}

## Configuration files
If you haven't provided a custom config file path when installing Adaptyst, the system-wide configuration file can be found in ```<your install prefix>/etc/adaptyst.conf```. Additionally, in case you want to provide your own local settings, any values set system-wide can be overridden and any other extra values can be added by a local config file in ```.adaptyst/adaptyst.conf``` inside your home directory. Both files follow exactly the same syntax.

If you want to use a different path for the system-wide config and/or local config **at runtime**, you can set the ```ADAPTYST_CONFIG``` and ```ADAPTYST_LOCAL_CONFIG``` environment variables respectively. Additionally, Adaptyst calls modules from inside ```<your install prefix>/opt/adaptyst/modules``` by default, but this path can also be changed at runtime and extra module search paths added by setting the ```ADAPTYST_MODULE_DIRS``` environment variable to a colon-separated list of paths (e.g. ```/opt/adaptyst/modules:/home/test/modules```). Similarly, Adaptyst looks for its support files inside ```<your install prefix>/opt/adaptyst```, but this path can be changed at runtime through the ```ADAPTYST_MISC_DIR``` environment variable. It is possible to vary most of these paths permanently as well when compiling Adaptyst from source, see [the installation guide](/install).

The currently-supported settings in the configuration files are shown below:
{{< details "Config file format with supported settings" >}}
```
# The Adaptyst core doesn't use configuration files in the current version.
# However, any update in the future may introduce new settings here.
```
{{< /details >}}

{{< callout context="note" title="Module ordering in ```ADAPTYST_MODULE_DIRS```" icon="outline/info-circle" >}}
In a list set in ```ADAPTYST_MODULE_DIRS```, modules found in earlier paths take precedence over modules found in later paths.
{{< /callout >}}

## Containers
Adaptyst can run in a Docker or Apptainer/Singularity container. For a quick start, the ready-to-use images will be provided by us soon (see [Installation](/install#container-images)).

{{< callout context="caution" title="Module-specific container options" icon="outline/alert-triangle" >}}
If you run Adaptyst in a containerised way, you must check if your modules should be set up in a specific way due to running in a container. See the documentation of your modules for more information. If the docs do not say anything, you can assume that the modules can run as usual in a container.
{{< /callout >}}

## Code regionisation
Adaptyst allows defining specific regions in your workflow to be analysed by modules. In the current version,
this can be done only by adding the following to your code:
```c
#include <adaptyst/inject.h>

// ...

adaptyst_region_start("your region name");

// Your code region

adaptyst_region_end("your region name");

// ...
```

If you decide to do so, you also need to link your program against ```libadaptyst_inject.so``` installed
automatically when setting up Adaptyst (in CMake, you can use the ```adaptyst::adaptyst_inject``` target).

If you use a different programming language than C/C++, you can still call ```adaptyst_region_start()```
and ```adaptyst_region_end()``` as long as it supports calling C functions.

Depending on the module, code regionisation may be either not supported, optional, or compulsory to use.
Check the documentation of your module for more details (if it doesn't mention code regionisation,
you can assume it is unsupported).

## Analysed source code packaging
By default, Adaptyst looks for and packs source code files within entities where your analysed program is run.

{{< callout context="caution" title="Varying source code packaging" icon="outline/alert-triangle" >}}
The current modular version of Adaptyst doesn't support varying how source code files are listed/packed. This will change in the future. Sorry for any inconvenience caused!
{{< /callout >}}

<!-- This behaviour can be changed by running ```adaptyst``` with the ```-c``` option. -->

<!-- You can then save the list of detected source code file paths to a text file or -->
<!-- print such list to a given file descriptor. In these cases, you can supply the resultant list to ```adaptyst-code``` to create a ZIP archive with the code files. ```adaptyst-code``` is a -->
<!-- Python script and has less strict setup requirements than the full Adaptyst suite ones. -->

<!-- The ZIP archive should be placed as ```src.zip``` inside ```<your performance analysis session>/system/<entity>``` (see "Structure of results" above). -->

<!-- Here's an example of running Adaptyst with a custom source code packing mode: -->
<!-- ``` -->
<!-- $ ls -->
<!-- <initial contents> -->
<!-- $ adaptyst -s system.yml -c file:code_paths.lst -d -- <command> -->
<!-- ... -->
<!-- $ ls -->
<!-- <initial contents> -->
<!-- code_paths.lst -->
<!-- <your performance analysis session> -->
<!-- $ adaptyst-code code_paths.lst -->
<!-- ... -->
<!-- $ ls -->
<!-- <initial contents> -->
<!-- code_paths.lst -->
<!-- <your performance analysis session> -->
<!-- src.zip -->
<!-- $ mv src.zip <your performance analysis session>/system/<entity> -->
<!-- $ -->
<!-- ``` -->

<!-- If you want to see how you can configure ```adaptyst-code``` to your needs, run ```adaptyst-code --help```. -->

<!-- {{< details "Help message printed by ```adaptyst-code --help```" >}} -->
<!-- ``` -->
<!-- usage: adaptyst-code [-h] [-o FILE] [-v] PATHS_FILE -->

<!-- Analysed code packaging tool for Adaptyst -->

<!-- positional arguments: -->
<!--   PATHS_FILE  path to a code paths file generated by Adaptyst -->
<!--               (usually as code_paths.lst) or written manually with -->
<!--               one source code file path per line (use "-" for stdin) -->

<!-- options: -->
<!--   -h, --help  show this help message and exit -->
<!--   -o FILE     path to an output ZIP archive to be produced (src.zip -->
<!--               in the current directory by default, use "-" for stdout) -->
<!--   -v          print path-processing-related errors to stderr (these -->
<!--               are not printed by default) -->
<!-- ``` -->
<!-- {{< /details >}} -->