..
 # Copyright (c) 2025, Arm Limited.
 #
 # SPDX-License-Identifier: MIT

####################
Installation & Setup
####################

*******************
System Requirements
*******************

Fastpath requires the following dependencies:

- **A Linux system with Python 3.x** is required to run the tool.
- **A separate Linux system as the SUT** is required, which must be configured
  according to the requirements at :doc:`configuresut`.
- **SSH access** is necessary for communication between the host system and the
  SUT.

*******************
Installing Fastpath
*******************

----------------------
Installing from Source
----------------------

First, optionally create and activate a Python virtual environment to install
all the Python package dependencies into:

.. code-block:: shell

  python3 -m venv ~/venv
  source ~/venv/bin/activate

To install Fastpath from the source repository, run:

.. code-block:: shell

  git clone https://git.gitlab.arm.com/tooling/fastpath.git
  pip install -r fastpath/fastpath/requirements.txt
  export PATH=$PWD/fastpath/fastpath:$PATH

----------------------
Verifying Installation
----------------------

Run the following command to verify installation:

.. code-block:: shell

  fastpath --help

If Fastpath is installed correctly, this command will display available options
and supported commands.

Fastpath commands are all of the form:

``fastpath [global-options] <noun> <verb> [command-options]``

So you can additionally get help on any specific noun (e.g. ``plan``) or verb
(e.g. ``exec``):

.. code-block:: shell

  fastpath plan --help
  fastpath plan exec --help

----------------------------
Configuring User Preferences
----------------------------

Fastpath has an extensible user preference system that allows users to customize
certain aspects. User preferences can be stored in the INI file at
``~/.fastpathpreferences`` or can be specified as environment variables. If a
preference is specified in both places, the environment variable takes
precedence.

Each preference has a category and a name, which maps to a string. To set and
get preferences in ``~/.fastpathpreferences``, use the ``fastpath preference``
noun:

.. code-block:: shell

  $ fastpath preference set --category default --name resultstore mysql://fpuser:MyPassword@my.sql.server.com/fastpath-db
  default.resultstore: mysql://fpuser:MyPassword@my.sql.server.com/fastpath-db

  $ fastpath preference get --category default --name resultstore
  default.resultstore: mysql://fpuser:MyPassword@my.sql.server.com/fastpath-db

When specified as an environment variable, concatenate the upper case category
and name as ``FASTPATH_<CATEGORY>_<NAME>``:

.. code-block:: shell

  $ export FASTPATH_DEFAULT_RESULTSTORE=mysql://fpuser:MyPassword@my.sql.server.com/fastpath-db

The following user preferences are currently defined:

========= =========== ======= ===========
categrory name        default description
========= =========== ======= ===========
default   resultstore <None>  For a command that requires a resultstore, the default resultstore to use if one is not specified explicitly on the command line.
global    library     <None>  Colon-separated list of paths to custom benchmark libraries. Benchmark includes are searched for relative to the current directory as well as relative to these paths.
========= =========== ======= ===========