Metadata-Version: 2.4
Name: asct
Version: 0.1.2
Summary: Arm System Characterization Tool
License: Arm Proprietary License
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: C
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: license_terms/license_agreement.txt
License-File: license_terms/third_party_licenses.txt
Requires-Dist: matplotlib>=3.9.4
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas>=2.3.0
Requires-Dist: scikit-learn>=1.6.1
Requires-Dist: seaborn>=0.13.2
Dynamic: license-file

![sdist](https://github.com/Arm-Debug/asct/actions/workflows/build-sdist.yml/badge.svg)
 [![Maintainability](https://qlty.sh/badges/ccf91760-a2b0-49e8-ae27-4f99deca7064/maintainability.svg)](https://qlty.sh/gh/Arm-Debug/projects/asct)
 [![Test Coverage](https://qlty.sh/badges/ccf91760-a2b0-49e8-ae27-4f99deca7064/test_coverage.svg)](https://qlty.sh/gh/Arm-Debug/projects/asct)

<!--toc:start-->
- [Arm System Characterization Tool](#arm-system-characterization-tool)
  - [Requirements](#requirements)
  - [Installing the ASCT PIP package and running ASCT](#installing-the-asct-pip-package-and-running-asct)
  - [Command line options](#command-line-options)
  - [Setting up a local virtual environment for development](#setting-up-a-local-virtual-environment-for-development)
    - [Note: Updating the binaries in a development virtual env](#note-updating-the-binaries-in-a-development-virtual-env)
    - [Python development loop tl;dr](#python-development-loop-tldr)
    - [C development loop tl;dr](#c-development-loop-tldr)
  - [Cleaning the tree](#cleaning-the-tree)
  - [Building the release PIP source package](#building-the-release-pip-source-package)
- [Creating a new release](#creating-a-new-release)
  - [Use ./scripts/release.sh](#use-scriptsreleasesh)
  - [Or update pyproject.toml and use GitHub UI](#or-update-pyprojecttoml-and-use-github-ui)
<!--toc:end-->

# Arm System Characterization Tool
Arm System Characterization Tool including various scripts and microbenchmarks
to characterize various bottlenecks of the system.

## Requirements
* System packages: Python3.9+, gcc, make
* Python packages:
  ```
  python -m ensurepip; pip install -r requirements_dev.txt
  ```

## Installing the ASCT PIP package and running ASCT
There are several options for installing and running ASCT:

1. Installing and running using uv
- Prerequisite: install uv via PIP on the system:
  ```
  sudo pip install uv --break-system-packages
  ```
  - Refer to https://docs.astral.sh/uv/getting-started/installation/ for
    details and alternative installation methods.
- Install ASCT using uv - this will make the `asct` command available to all users:
  ```
  UV_TOOL_BIN_DIR=/usr/local/bin sudo -E uv tool install /path/to/asct-<version>.tar.gz
  ```
- Run ASCT:
     ```
     sudo asct
     ```
     ```
     asct
     ```

2. Installing and running using virtual environments
 - Prerequisite: create a local virtual environment and activate it:
   ```
   python3 -m venv asct_venv && source asct_venv/bin/activate
   ```
 - Install ASCT using PIP:
   ```
   pip install /path/to/asct-<version>.tar.gz
   ```
 - Run ASCT (note: due to ASCT having to run under sudo, the command needs to pass
   the virtualenv's environment variables to the root user):
   - Option 1:
        ```
        sudo bash -c "source asct_venv/bin/activate ; asct"
        ```
   - Option 2:
        ```
        sudo -E env PATH=$PATH asct
        ```

3. Installing and running it as a system Python package (least safe option):
  - Install ASCT using sudo pip (this will make the asct command available to
    all users but may break existing packages):
    ```
    sudo pip install /path/to/asct-<version>.tar.gz --break-system-packages
    ```
  - Run ASCT:
       ```
       sudo asct
       ```

- **NOTE:** `asct` with no arguments currently displays available options, however
  in future will run a default set of characterization benchmarks, and provide a
  single unified report containing results and information from sysreport.


## Command line options
- `asct --help`
  - Display help and usage options

- `--format`, `-f` `[stdout, csv, json]`
  - Specify the output format, either to the terminal via stdout (default), CSV
    or JSON files
    - e.g.
      ```
      asct --format=json --sysreport
      ```
- `--log-level`, `-L` `[debug,info,warning,error,critical]`
  - Specify verbosity. By default the level is `info`, but this can be
    configured.
- `--log-file` LOG_FILE
  - Specify an output file for logging messages as determined above by
    `--log-level` parameter (in addition to stderr)

- `--sysreport` or `-s`
  - Display system information only and quit
  - This information is included by default with any benchmark run and is not
    required to be passed (except when outputting to CSV)

- `--memory` or `-m` `[m1] [m2] [...]`
  - Run memory characterization benchmarks
    - Multiple benchmarks can be passed as arguments to a single command
    - e.g.
      ```
      asct --memory latency-sweep idle-latency
      ```
    - For full options see:
      ```
      asct --help
      ```

## Setting up a local virtual environment for development

The tool can be installed locally using pip's 'editable install' option
(pip install -e). This allows changes to the source tree to be picked up
immediately, without needing to reinstall the package:
1. Clone this repository
2. Run:
   ```
   ./build.sh devel
   ```
  This will create the virtual environment,
   build the C binaries and install the tool.
   
3. [Optional] Run:
   ```
   ./build.sh activate
   ```
   This will start a prompt as sudo in the
   virtual environment where the tool was installed. If step 2 is skipped, this
   command will also run step 2. The command will try to use the shell installed
   on the system to launch that prompt.
4. Alternatively, you can do one of the following:

   a. Activate the development virtual env manually and run the tool as sudo:
      ```
      source devel/venv/bin/activate
      sudo -E env PATH=$PATH asct
      ```
      or

   b. Launch a new sudo prompt after activating the virtual env:
      ```
      sudo $SHELL -c "source devel/venv/bin/activate; exec $SHELL"
      ```
      Note: this new virtual env will behave as expected, but won't provide the `deactivate`
      function nor will it have its `(venv)` name next to the username.


### Note: Updating the binaries in a development virtual env
After step 3, you can rebuild all binaries by running:
```
./build.sh bin
```
to rebuild all binaries.

#### Note
  Step 2 (or step 3 if 2 is omitted) will build the binaries. 
  ```
  ./build.sh bin
  ```
  This is primarily used to quickly rebuild binaries after making changes to the
  source code.

### Python development loop tl;dr
1. Clone
2. Activate the virtual env in devel/venv manually or run:
   ```
   ./build.sh activate
   ```
3. Modify Python code
4. Run:
   ```
   asct
   ```
5. Go to 3

### C development loop tl;dr
1. Clone
2. Activate the virtual env in devel/venv manually or run:
   ```
   ./build.sh activate
   ```
3. Modify C code
4. Rebuild the binaries:
   ```
   ./build.sh bin
   ```
5. Run:
   ```
   asct
   ```
6. Go to 3


## Cleaning the tree
Run:  
```
./build.sh clean
```
This removes all artifact directories and cleans all the C code.


## Building the release PIP source package
The tool can be built into a standard Python package that can be installed
on a target machine. The resulting package can be found in
`dist/asct-<version>.tar.gz`:

1. Clone this repository
2. Run:
   ```
   ./build.sh release
   ```
    to build `dist/asct-<version>.tar.gz`
3. [Optional] For an extra quick sanity check, add --quick-test to the build command:
   ```
   ./build.sh release --quick-test
   ```
   This will create a virtual env, install the tool,
   run a simple command, and delete the virtual env.

# Creating a new release

This project uses semantic versioning (major.minor.patch).
The version info is contained in the `version` element of [pyproject.toml](pyproject.toml)
and also as git tags [v0.1.0](https://github.com/Arm-Debug/asct/releases/tag/v0.1.0)
There are two paths to creating a new release, and both help check that the tags and pyproject.toml are in sync. They both trigger the same [release](/.github/workflows/on-release.yml) workflow that builds and uploads artifacts. You can either use the [release.sh](scripts/release.sh) script, or update the pyproject.toml and use the GitHub UI.

## Use ./scripts/release.sh

The simplest way to create a new patch release is to run:
```
./scripts/release.sh
```
It'll fetch tags and use an incremented patch version, or use what you've put in pyproject.toml if that's newer.
It'll update pyproject.toml if needed, create a release/vX.Y.Z branch and open a PR for it (if you have `gh` installed).

   Run 
      ```
      ./scripts/release.sh --help
      ```
   to see other options, like `major`, `minor`, `patch` (the default) or `vX.Y.Z`

Once the release pull request is merged, [on-release-pr-merged.yml](.github/workflows/on-release-pr-merged.yml) will trigger.
It tags the merged commit for the release PR, and creates a GitHub release from that.

## Or update pyproject.toml and use GitHub UI

For this flow, you _must_ update [pyproject.toml](pyproject.toml)'s version number.
Then [create a new release](https://github.com/Arm-Debug/asct/releases/new) with a matching `v<m.m.p>` tag. So if pyproject.toml has `0.1.0` the tag should be `v0.1.0`.
The [release](/.github/workflows/release.yml) workflow will check that the tag and .toml versions match. If there's a mismatch, then we won't upload artifacts and you should probably delete the release and tag and try again with an updated .toml.

