# Set up and build the example application

## In this learning path

- [Introduction](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-memory-access/)
- [Understand CPU memory hierarchy and address translation](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-memory-access/how-to-0/)
- [Set up and build the example application](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-memory-access/how-to-1/)
- [Profile memory access behavior with Arm Performix](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-memory-access/how-to-2/)
- [Optimize the application manually and with the Arm MCP Server](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-memory-access/how-to-3/)
- [Next Steps](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-memory-access/_next-steps/)

In this section, you’ll install the required system packages, clone the orbiting galaxies example repository, and build the workload binaries. You can also run a visualization to confirm the simulation is working before you profile it.

Use your remote Arm server for all build and run steps. This example uses an Amazon EC2 `c7g.metal` instance running Ubuntu 24.04 LTS.

## Install Arm Performix

Install and configure Arm Performix using the [Performix install guide](https://learn.arm.com/install-guides/performix/) on both your local machine and the remote Arm server.

## Install the required system packages

Run the following command, replacing `apt` with the package manager for your Linux distribution.

```
sudo apt update
sudo apt install -y git cmake build-essential python3 python3-venv python3-pip
```

## Enable the Arm SPE PMU driver if not already loaded

To check whether the driver is already loaded, run:

```
lsmod | grep arm_spe_pmu
```

If the command returns output, the driver is loaded and you can skip this step. If it returns nothing, run the following commands to load it. This is required on Ubuntu 24.04 LTS in AWS, but may not be needed on other platforms.

```
sudo apt install -y linux-modules-extra-$(uname -r)
sudo modprobe arm_spe_pmu
```

If you’re using a `c7g.metal` instance, you also need to turn Kernel Page Table Isolation (KPTI) off.

The fastest way on AWS is to use an editor to add `kpti=off` to the `GRUB_CMDLINE_LINUX_DEFAULT` line in `/etc/default/grub.d/50-cloudimg-settings.cfg`.

After editing the file, run:

```
sudo update-grub
sudo reboot
```

For a complete explanation of SPE, see [Enable Arm SPE for Performix memory access analysis](https://learn.arm.com/learning-paths/servers-and-cloud-computing/spe-on-performix/).

## Build the sample application

After setting up the build environment, clone and build the sample application.

### Clone the example repository

Clone the orbiting galaxies repository and check out the tagged release to work from a known starting point:

```
git clone https://github.com/arm-education/Orbiting-Galaxy-Example.git
cd Orbiting-Galaxy-Example
git checkout -b my-work v1.0.3
```

### Build with CMake

Build the project using CMake:

```
mkdir -p build
cd build
cmake ..
cmake --build . --parallel
```

This produces three binaries in `build/`:
- `baseline` — the unoptimized reference binary used for profiling
- `users_solution` — an editable copy of `baseline` for you to optimize manually
- `optimized` — a pre-built reference solution showing the expected outcome

## Set up a Python virtual environment and run visualization

After building the application, from the repository root, run:

```
cd ..
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r scripts/requirements.txt
```

Generate simulation frames and create the GIF:

```
cd build
./baseline --visualize
python3 ../scripts/visualize.py galaxy_baseline.bin
```

The script reads simulation data from `galaxy_baseline.bin` and writes a GIF file `assets/galaxy_baseline.gif`.

![Orbiting galaxies workload visualization](https://learn.arm.com/learning-paths/servers-and-cloud-computing/performix-memory-access/galaxy_compressed.gif)  
*Orbiting galaxies workload visualization*

Use `--visualize` only for understanding the workload behavior. Don’t include visualization mode in profiling runs because file I/O alters the measured runtime characteristics.

## What you’ve accomplished and what’s next

You’ve now set up and built an orbiting galaxy application on an Arm-based instance by setting up a build environment and cloning the app from a GitHub repo. You’ve also run a visualization to confirm that the application works as expected.

Next, you’ll profile memory access behavior using Arm Performix.