### Install CompilerGym Examples Package

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/llvm_autotuning/README.md

Install the package containing example code for CompilerGym from the repository root.

```bash
cd examples
python setup.py install
```

--------------------------------

### Run Unrolling CompilerGym Service Example with Bazel

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/example_unrolling_service/README.md

Execute the example service using Bazel. This command builds and runs the example service, demonstrating its functionality.

```shell
$ bazel run //examples/example_unrolling_service:example
```

--------------------------------

### Run Example Without Bazel

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/loop_optimizations_service/README.md

Execute the example script for the loop optimizations service by navigating to the examples directory and running the Python script directly.

```sh
cd examples
python3 loop_optimizations_service/demo_without_bazel.py
```

--------------------------------

### Run Example Script with Bazel

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/loop_optimizations_service/README.md

Execute the example script for the loop optimizations service using Bazel.

```sh
bazel run //examples/loop_optimizations_service:example
```

--------------------------------

### Build and Install with Bazel

Source: https://github.com/facebookresearch/compilergym/blob/development/INSTALL.md

Builds and installs the 'compiler_gym' Python package using Bazel. Requires running 'make install' before testing.

```sh
make install
```

--------------------------------

### Run Example Service Demo with Bazel

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/example_compiler_gym_service/README.md

Execute the demo script for the example CompilerGym service using Bazel. This command builds and runs the demonstration of the service.

```sh
bazel run -c opt //examples/example_compiler_gym_service:demo
```

--------------------------------

### Run Unrolling CompilerGym Service Example without Bazel

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/example_unrolling_service/README.md

Execute the example service directly using Python without Bazel. This requires building the 'loop_unroller' tool first and then running the demo script from the 'examples' directory.

```shell
cd examples
$ python3 example_unrolling_service/demo_without_bazel.py
```

--------------------------------

### Test Docker Installation

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Verify that Docker is installed and running correctly.

```bash
docker run hello-world
```

--------------------------------

### Install CompilerGym

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/getting-started.ipynb

Installs the latest CompilerGym release using pip. This is the primary method for getting started with the package.

```python
!pip install compiler_gym
```

--------------------------------

### Example: Genetic Algorithm Search for GCC Autotuning

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/gcc_autotuning/README.md

Example command to run a genetic algorithm search with a specified budget and repetitions on two CHStone benchmarks.

```bash
python -m gcc_autotuning.tune \
    --gcc_bin=docker:gcc:11.2.0 \
    --seed=204 \
    --search=genetic \
    --gcc_search_budget=100 \
    --gcc_search_repetitions=3 \
    --gcc_benchmark=benchmark://chstone-v0/aes,benchmark://chstone-v0/sha
```

--------------------------------

### Get Help for env.step

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/getting-started.ipynb

Use `help()` to get detailed documentation for environment functions like `env.step`.

```python
help(env.step)
```

--------------------------------

### Install CompilerGym and RLlib

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/rllib.ipynb

Installs the necessary packages for CompilerGym and RLlib. It also prints the versions of the installed libraries.

```python
import compiler_gym
import ray

print("compiler_gym version:", compiler_gym.__version__)
print("ray version:", ray.__version__)
```

--------------------------------

### ProGraML Graph Representation Example

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/llvm/index.md

Demonstrates accessing the ProGraML observation space, which returns a networkx.MultiDiGraph object representing LLVM-IR. Shows how to get the graph, number of nodes, and details of a specific node and edge.

```pycon
>>> G = env.observation["Programl"]
>>> G
<networkx.classes.multidigraph.MultiDiGraph object at 0x7f9d8050ffa0>
>>> G.number_of_nodes()
6326
>>> G.nodes[1000]
{'block': 8, 'features': {'full_text': ['%439 = load double, double* @tmp2, align 8']}, 'function': 0, 'text': 'load', 'type': 0}
>>> G.edge[0, 1, 0]
{'flow': 2, 'position': 0}
```

--------------------------------

### Run Example Service Unit Tests with Bazel

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/example_compiler_gym_service/README.md

Execute the unit tests for the example CompilerGym service using Bazel. This command builds and runs all tests within the specified directory.

```sh
bazel test //examples/example_compiler_gym_service/...
```

--------------------------------

### Install Linux Dependencies with apt

Source: https://github.com/facebookresearch/compilergym/blob/development/INSTALL.md

Installs required packages on Debian-based Linux systems using apt. Downloads and sets up Bazel and Hadolint, and installs Go tools.

```sh
sudo apt install -y clang clang-format golang libjpeg-dev \
  libtinfo5 m4 make patch zlib1g-dev tar bzip2 wget
mkdir -pv ~/.local/bin
wget https://github.com/bazelbuild/bazelisk/releases/download/v1.7.5/bazelisk-linux-amd64 -O ~/.local/bin/bazel
wget https://github.com/hadolint/hadolint/releases/download/v1.19.0/hadolint-Linux-x86_64 -O ~/.local/bin/hadolint
chmod +x ~/.local/bin/bazel ~/.local/bin/hadolint
go install github.com/bazelbuild/buildtools/buildifier@latest
GO111MODULE=on go install github.com/uber/prototool/cmd/prototool@dev
export PATH="$HOME/.local/bin:$PATH"
export CC=clang
export CXX=clang++
```

--------------------------------

### CMake Build Option: Enable Examples

Source: https://github.com/facebookresearch/compilergym/blob/development/INSTALL.md

Configures the CMake build to include additional tools required by some examples.

```sh
-DCOMPILER_GYM_BUILD_EXAMPLES=ON
```

--------------------------------

### Install CompilerGym using pip

Source: https://github.com/facebookresearch/compilergym/blob/development/INSTALL.md

Install the latest release of CompilerGym using pip. This command also upgrades an existing installation.

```bash
pip install -U compiler_gym
```

--------------------------------

### Example: Grid Sweep Autotuning Configuration

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/llvm_autotuning/README.md

Configuration for a grid sweep autotuning experiment, varying search time and episode length.

```bash
python -m llvm_autotuning.tune -m \
    experiment=my-tuning-experiment \
    num_replicas=10 \
    benchmarks=csmith-50 \
    autotuner=nevergrad \
    autotuner.optimization_target=codesize \
    autotuner.search_time_seconds=300,600 \
    autotuner.algorithm_config.episode_length=100,200,300
```

--------------------------------

### Test Installed Package

Source: https://github.com/facebookresearch/compilergym/blob/development/INSTALL.md

Runs the test suite on the installed 'compiler_gym' package. Refer to 'make help' for test options.

```sh
make test
```

--------------------------------

### Example Usage of MLIR Environment with RL Wrapper

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/mlir.md

Demonstrates how to create, reset, and take a step in the MLIR environment using the RL wrapper.

```python
import gym
from compiler_gym.wrappers.mlir import make_mlir_rl_wrapper_env

env = gym.make("mlir-v0")
wrapper = make_mlir_rl_wrapper_env(env)
wrapper.reset()
observation, reward, done, info = wrapper.step(wrapper.action_space.sample())
```

--------------------------------

### Install CMake from Source

Source: https://github.com/facebookresearch/compilergym/blob/development/INSTALL.md

Downloads, installs, and adds CMake version 3.20.5 to the user's local bin directory.

```sh
wget https://github.com/Kitware/CMake/releases/download/v3.20.5/cmake-3.20.5-linux-x86_64.sh -O cmake.sh
bash cmake.sh --prefix=$HOME/.local --exclude-subdir --skip-license
rm cmake.sh
export PATH=$HOME/.local/bin:$PATH
```

--------------------------------

### Example: Nevergrad Code Size Autotuning

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/llvm_autotuning/README.md

Example command to run Nevergrad autotuning for code size optimization for 10 minutes with 32 parallel workers.

```bash
python -m llvm_autotuning.tune -m \
    experiment=my-experiment \
    outputs=/tmp/logs \
    executor.cpus=32 \
    num_replicas=1 \
    autotuner=nevergrad \
    autotuner.optimization_target=codesize \
    autotuner.search_time_seconds=600
```

--------------------------------

### Run Unrolling CompilerGym Service Unit Tests with Bazel

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/example_unrolling_service/README.md

Execute the unit tests for the example service using Bazel. This command ensures the example service functions correctly.

```shell
$ bazel test //examples/example_unrolling_service:env_tests
```

--------------------------------

### Basic CompilerGym Environment Usage in Python

Source: https://github.com/facebookresearch/compilergym/blob/development/README.md

Demonstrates how to import, make, reset, render, step, and close a CompilerGym environment. This example shows creating an LLVM environment with specific benchmark, observation, and reward spaces.

```python
import compiler_gym                      # imports the CompilerGym environments
env = compiler_gym.make(                 # creates a new environment (same as gym.make)
    "llvm-v0",                           # selects the compiler to use
    benchmark="cbench-v1/qsort",         # selects the program to compile
    observation_space="Autophase",       # selects the observation space
    reward_space="IrInstructionCountOz", # selects the optimization target
)
env.reset()                              # starts a new compilation session
env.render()                             # prints the IR of the program
env.step(env.action_space.sample())      # applies a random optimization, updates state/reward/actions
env.close()                              # closes the environment, freeing resources
```

--------------------------------

### Install Development Requirements

Source: https://github.com/facebookresearch/compilergym/blob/development/INSTALL.md

Installs development environment requirements for contributing to CompilerGym.

```sh
make dev-init
```

--------------------------------

### Loop Tree Visualization Example

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/loop_tool.md

This example demonstrates how the loop_tree observation space represents the program's computation. The cursor is indicated by '<-- cursor' and highlights the current loop being pointed to by the action_state.

```none
for a in 341 r 1 : L0 [thread] <-- cursor
 for a' in 3 : L1
  for a'' in 1 : L2
   %0[a] <- read()
  for a'' in 1 : L4
   %1[a] <- read()
  for a'' in 1 : L6
   %2[a] <- add(%0, %1)
  for a'' in 1 : L8
   %3[a] <- write(%2)
```

```none
for a in 341 r 1 : L0 [thread]
 for a' in 3 : L1              <-- cursor
  for a'' in 1 : L2
   %0[a] <- read()
  for a'' in 1 : L4
   %1[a] <- read()
  for a'' in 1 : L6
   %2[a] <- add(%0, %1)
  for a'' in 1 : L8
   %3[a] <- write(%2)
```

```none
for a in 341 r 1 : L0 [thread]
 for a' in 3 : L1
  for a'' in 1 : L2            <-- cursor
   %0[a] <- read()                |
  for a'' in 1 : L4            <--+
   %1[a] <- read()                |
  for a'' in 1 : L6            <--+
   %2[a] <- add(%0, %1)           |
  for a'' in 1 : L8            <--+
   %3[a] <- write(%2)
```

--------------------------------

### Install GCC on macOS

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Install GCC on macOS using Homebrew.

```bash
brew install gcc
```

--------------------------------

### Install Docker on Linux

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Install Docker on Debian-based Linux distributions.

```bash
sudo apt-get update && sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo \
    "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
    $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update && sudo apt-get install docker-ce docker-ce-cli containerd.io
```

--------------------------------

### Install Docker on macOS

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Use Homebrew to install Docker on macOS.

```bash
brew install docker
```

--------------------------------

### Handle Docker Initialization Error

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Example of EnvironmentNotSupported exception when Docker client fails to initialize.

```python
compiler_gym.make("gcc-v0")
```

--------------------------------

### Install GCC on Linux

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Install GCC on Debian-based Linux distributions.

```bash
sudo apt-get install gcc
```

--------------------------------

### Example: Reproduce Paper Experiments with GCC Autotuning

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/gcc_autotuning/README.md

Command to reproduce experiments from a research paper, using multiple search strategies and a comprehensive list of CHStone benchmarks.

```bash
python -m gcc_autotuning.tune \
    --gcc_bin=docker:gcc:11.2.0 \
    --seed=204 \
    --search=random,hillclimb,genetic \
    --gcc_search_budget=1000 \
    --gcc_search_repetitions=3 \
    --gcc_benchmark=benchmark://chstone-v0/adpcm,benchmark://chstone-v0/aes,benchmark://chstone-v0/blowfish,benchmark://chstone-v0/dfadd,benchmark://chstone-v0/dfdiv,benchmark://chstone-v0/dfmul,benchmark://chstone-v0/dfsin,benchmark://chstone-v0/gsm,benchmark://chstone-v0/jpeg,benchmark://chstone-v0/mips,benchmark://chstone-v0/motion,benchmark://chstone-v0/sha
```

--------------------------------

### Print CompilerGym Version

Source: https://github.com/facebookresearch/compilergym/blob/development/leaderboard/SUBMISSION_TEMPLATE.md

Use this command to print the installed version of CompilerGym.

```bash
python -c 'import compiler_gym; print(compiler_gym.__version__)'
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/facebookresearch/compilergym/blob/development/INSTALL.md

Sets up a conda environment named 'compiler_gym' with Python 3.8 and installs core build dependencies.

```sh
conda create -y -n compiler_gym python=3.8
conda activate compiler_gym
conda install -y -c conda-forge cmake doxygen pandoc patchelf
```

--------------------------------

### Install macOS Dependencies with Homebrew

Source: https://github.com/facebookresearch/compilergym/blob/development/INSTALL.md

Installs necessary build tools and libraries on macOS using Homebrew. Sets environment variables for zlib.

```sh
brew install bazelisk buildifier clang-format hadolint prototool zlib
export LDFLAGS="-L/usr/local/opt/zlib/lib"
export CPPFLAGS="-I/usr/local/opt/zlib/include"
export PKG_CONFIG_PATH="/usr/local/opt/zlib/lib/pkgconfig"
```

--------------------------------

### Handle Local Binary Not Found Error

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Example of EnvironmentNotSupported exception when a local GCC binary cannot be found or executed.

```python
compiler_gym.make("gcc-v0", gcc_bin="gcc-11")
```

--------------------------------

### External Project Setup for ProGraML

Source: https://github.com/facebookresearch/compilergym/blob/development/external/programl/CMakeLists.txt

Configures an external project for ProGraML, specifying its source URL, hash, and build options. This is used to download and prepare the ProGraML source code.

```cmake
externalproject_add(
    programl
    PREFIX "${CMAKE_CURRENT_BINARY_DIR}/programl"
    URL
        "https://github.com/ChrisCummins/ProGraML/archive/83f00233b04f4ecf7f12a79c80ffe23c2953913f.tar.gz"
    URL_HASH
        "SHA256=704826311b842b3ffc2dedcce593fdd319d76e95bdf5386985768007ebb22316"
    DOWNLOAD_NO_EXTRACT FALSE
    CONFIGURE_COMMAND ""
    BUILD_COMMAND ""
    INSTALL_COMMAND ""
)
```

--------------------------------

### Tabular Q-Learning Example

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/README.md

A simple tabular Q-learning agent for the LLVM environment. It uses selected features from the Autophase observation space to find the best action sequence for a given training program using online Q-learning.

```python
import gym

import compiler_gym.spaces
from compiler_gym.util.training import train


def main():
    env = gym.make("llvmir-v0",
                 # Use a subset of the available passes.
                 # See "compiler_gym.util.passes.COMPILER_PASSES" for a list of all passes.
                 action_space=compiler_gym.spaces.ActionSpace.from_spec(
                     """
                     passes:
                       - irpass.loop_unroll
                       - irpass.loop_vectorize
                       - irpass.loop_fission
                     """
                 ),
                 # Use a small benchmark for faster iteration.
                 # See "compiler_gym.datasets.Benchmark" for a list of all benchmarks.
                 benchmarks=["bitcnts", "rijndael", "sha", "dijkstra"],
                 # Limit the number of steps per episode.
                 max_steps=20
    )

    # Instantiate the Q-learning model.
    # See https://pytorch.org/docs/stable/generated/torch.nn.Module.html
    class QLearning(nn.Module):
        def __init__(self, env):
            super().__init__()
            self.q_values = nn.Sequential(
                nn.Linear(env.observation_space.shape[0], 128),
                nn.ReLU(),
                nn.Linear(128, env.action_space.n),
            )

        def forward(self, x):
            return self.q_values(x)

    model = QLearning(env)
    optimizer = optim.Adam(model.parameters(), lr=0.001)

    # Train the agent.
    # See https://github.com/facebookresearch/CompilerGym/blob/main/compiler_gym/util/training.py
    train(
        env=env,
        policy_model=model.q_values,
        optimizer=optimizer,
        n_episodes=1000,
        # Use a discount factor of 0.99.
        # See https://en.wikipedia.org/wiki/Discount_factor
        gamma=0.99,
        # Use a learning rate of 0.001.
        learning_rate=0.001,
        # Use a batch size of 32.
        batch_size=32,
        # Use a target Q-learning update frequency of 10.
        target_update_frequency=10,
    )


if __name__ == "__main__":
    main()

```

--------------------------------

### Run Python Service Demo Without Bazel

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/example_compiler_gym_service/README.md

Run the Python demo script for the example CompilerGym service directly, without using the Bazel build system. This is possible because the Python service has no compiled code.

```sh
cd examples
python3 example_compiler_gym_service/demo_without_bazel.py
```

--------------------------------

### Configure and Build with CMake

Source: https://github.com/facebookresearch/compilergym/blob/development/INSTALL.md

Configures the build using CMake with specified C/C++ compilers and then builds the project. Installs the Python package using pip.

```sh
cmake \
  -DCMAKE_C_COMPILER=clang \
  -DCMAKE_CXX_COMPILER=clang++ \
  -S "<path to source directory>" \
  -B "<path to build directory>"

cmake --build "<path to build directory>"

pip install "<path to build directory>/py_pkg/dist/compiler_gym*.whl" --force-reinstall
```

--------------------------------

### Run Custom Unroller without Bazel

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/loop_optimizations_service/opt_loops/README.md

Execute the custom unroller tool from the examples directory, specifying input LLVM IR, unroll count, vector width, and output YAML path.

```bash
$ cd examples
$ loop_optimizations_service/opt_loops -- <input>.ll --funroll-count=<num> --force-vector-width=<num> -S -o <output>.ll --emit-yaml=<path to output yaml file>
```

--------------------------------

### Actor-Critic Example with PyTorch

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/README.md

A basic actor-critic agent implemented in PyTorch for optimizing program size using LLVM compiler passes. It selects passes sequentially to minimize instructions, with configurable subsets of passes and episode lengths.

```python
import gym

import torch
import torch.nn as nn
import torch.optim as optim

import compiler_gym.spaces
from compiler_gym.util.training import train


def main():
    env = gym.make("cbench-v0",
                 # Use a subset of the available passes.
                 # See "compiler_gym.util.passes.COMPILER_PASSES" for a list of all passes.
                 action_space=compiler_gym.spaces.ActionSpace.from_spec(
                     """
                     passes:
                       - irpass.loop_unroll
                       - irpass.loop_vectorize
                       - irpass.loop_fission
                     """
                 ),
                 # Use a small benchmark for faster iteration.
                 # See "compiler_gym.datasets.Benchmark" for a list of all benchmarks.
                 benchmarks=["bitcnts", "rijndael", "sha", "dijkstra"],
                 # Limit the number of steps per episode.
                 max_steps=20
    )

    # Instantiate the actor-critic model.
    # See https://pytorch.org/docs/stable/generated/torch.nn.Module.html
    class ActorCritic(nn.Module):
        def __init__(self, env):
            super().__init__()
            self.policy = nn.Sequential(
                nn.Linear(env.observation_space.shape[0], 128),
                nn.ReLU(),
                nn.Linear(128, env.action_space.n),
            )
            self.value = nn.Sequential(
                nn.Linear(env.observation_space.shape[0], 128),
                nn.ReLU(),
                nn.Linear(128, 1),
            )

        def forward(self, x):
            return self.policy(x), self.value(x)

    model = ActorCritic(env)
    optimizer = optim.Adam(model.parameters(), lr=0.001)

    # Train the agent.
    # See https://github.com/facebookresearch/CompilerGym/blob/main/compiler_gym/util/training.py
    train(
        env=env,
        policy_model=model.policy,
        value_model=model.value,
        optimizer=optimizer,
        n_episodes=1000,
        # Use a discount factor of 0.99.
        # See https://en.wikipedia.org/wiki/Discount_factor
        gamma=0.99,
        # Use a learning rate of 0.001.
        learning_rate=0.001,
        # Use a batch size of 32.
        batch_size=32,
        # Use a value loss coefficient of 0.5.
        value_loss_coeff=0.5,
        # Use an entropy bonus coefficient of 0.01.
        entropy_bonus_coeff=0.01,
    )


if __name__ == "__main__":
    main()

```

--------------------------------

### Install Python Package Rule

Source: https://github.com/facebookresearch/compilergym/blob/development/compiler_gym/CMakeLists.txt

Defines a CMake rule to install the built Python package. It uses pip to install the wheel file and depends on the python_package rule.

```cmake
string(CONCAT _CMD """${Python3_EXECUTABLE}" -m pip install --upgrade --no-deps --force-reinstall"""
    " "${_PY_PKG_OUT_DIR}/dist/${_PY_PGK_FILE_NAME}"
)
g_genrule(
  NAME install_python_package
  COMMAND "${_CMD}"
  DEPENDS ::python_package
  EXCLUDE_FROM_ALL
)
```

--------------------------------

### Run RLlib PPO Training Loop

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/rllib.ipynb

Initializes Ray, registers the CompilerGym environment, and runs a short PPO training loop. Configure rollout and training batch sizes for demonstration purposes.

```python
import ray
from ray.rllib.agents.ppo import PPOTrainer

# (Re)Start the ray runtime.
if ray.is_initialized():
  ray.shutdown()
ray.init(include_dashboard=False, ignore_reinit_error=True)

tune.register_env("compiler_gym", make_training_env)

analysis = tune.run(
    PPOTrainer,
    checkpoint_at_end=True,
    stop={
        "episodes_total": 500,
    },
    config={
        "seed": 0xCC,
        "num_workers": 1,
        # Specify the environment to use, where "compiler_gym" is the name we 
        # passed to tune.register_env().
        "env": "compiler_gym",
        # Reduce the size of the batch/trajectory lengths to match our short 
        # training run.
        "rollout_fragment_length": 5,
        "train_batch_size": 5,
        "sgd_minibatch_size": 5,
    }
)
```

--------------------------------

### List Available Environments

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/getting_started.md

Use `compiler_gym.bin.service --ls_env` to list all available CompilerGym environments.

```bash
$ python -m compiler_gym.bin.service --ls_env
llvm-v0
...
```

--------------------------------

### Install Linux Build Dependencies for CMake

Source: https://github.com/facebookresearch/compilergym/blob/development/INSTALL.md

Installs essential build tools for compiling with CMake on Linux.

```sh
sudo apt-get install g++ lld autoconf libtool ninja-build ccache git
```

--------------------------------

### Train PPO Model with LLVM InstCount

Source: https://github.com/facebookresearch/compilergym/blob/development/leaderboard/llvm_instcount/ppo/README.md

This script sets up the environment and trains the PPO model. Ensure ghostscript is excluded from the benchmark file for exact reproduction. The training runs for 10 hours with progress logged every 30 minutes.

```python
benchmarks = []
f = open("cbench-v1.txt", "r")
for line in f:
    benchmarks.append(line.strip())
f.close()

env = llvm_wrapper(benchmarks, max_episode_steps=200, steps_in_observation=True)

ppo_training = PPO(env)
ppo_training.train(log_progress=True, training_time=60 * 60 * 10, progress_log_rate=60 * 30)
Evaluation.evaluate(benchmarks, "default", additional_steps_for_max=500, max_trials_per_benchmark=100000,
                    max_time_per_benchmark=60 * 1)
```

--------------------------------

### Describe Environment Capabilities

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/getting_started.md

Use `compiler_gym.bin.service --env=<env_name>` to view datasets, observation spaces, and reward spaces for a specific environment.

```bash
$ python -m compiler_gym.bin.service --env=llvm-v0

Datasets
--------

+----------------------------+--------------------------+------------------------------+
| Dataset                    | Num. Benchmarks [#f1]_   | Description                  |
+----------------------------+--------------------------+------------------------------+
| benchmark://anghabench-v0  | 1,042,976                | Compile-only C/C++ functions |
+----------------------------+--------------------------+------------------------------+
| benchmark://blas-v0        | 300                      | Basic linear algebra kernels |
+----------------------------+--------------------------+------------------------------+
...

Observation Spaces
------------------

+--------------------------+----------------------------------------------+
| Observation space        | Shape                                        |
+==========================+==============================================+
| Autophase                | `Box(0, 9223372036854775807, (56,), int64)`  |
+--------------------------+----------------------------------------------+
| AutophaseDict            | `Dict(ArgsPhi:int<0,inf>, BB03Phi:int<0,...` |
+--------------------------+----------------------------------------------+
| BitcodeFile              | `str_list<>[0,4096.0])`                      |
+--------------------------+----------------------------------------------+
...

```

--------------------------------

### Create GCC Environment with Local Binary

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Instantiate a GCC environment using a local GCC binary specified by name.

```python
import compiler_gym
env = compiler_gym.make("gcc-v0", gcc_bin="gcc-11")
```

--------------------------------

### LLVM RL Training Directory Layout

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/llvm_rl/README.md

Illustrates the standard directory structure for training outputs, including logs, configurations, and checkpoints.

```shell
# The top level outputs for this run:
${outputs}/${experiment}/${YYY-MM-DD}/${hh-mm-ss}/
# Logs generated by the slurm worker:
${outputs}/${experiment}/${YYY-MM-DD}/${hh-mm-ss}/slurm_logs
# Each configuration of a multi-run gets its own directory using an ascending job ID:
${outputs}/${experiment}/${YYY-MM-DD}/${hh-mm-ss}/config-${job_id}
# A copy of all logging messages from the training job:
${outputs}/${experiment}/${YYY-MM-DD}/${hh-mm-ss}/config-${job_id}/train.log
# This directory contains an exact copy of the configs used:
${outputs}/${experiment}/${YYY-MM-DD}/${hh-mm-ss}/config-${job_id}/hydra
# RLlib checkpoints:
${outputs}/${experiment}/${YYY-MM-DD}/${hh-mm-ss}/config-${job_id}/train/${experiment}-0_0_2021-07-23_18-11-04
```

--------------------------------

### Run Tabular Q Evaluation (Short)

Source: https://github.com/facebookresearch/compilergym/blob/development/leaderboard/llvm_instcount/tabular_q/README.md

Executes the tabular Q-learning evaluation with short episode settings. Ensure all parameters are correctly configured before running.

```shell
python tabular_q_eval.py --episodes=2000 --episode_length=5 --learning_rate=0.1 --discount=1 --log_every=0
```

--------------------------------

### Interactive Environment Session

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/getting_started.md

Launch an interactive text-based user interface for CompilerGym environments using `compiler_gym.bin.manual_env`.

```bash
$ python -m compiler_gym.bin.manual_env --env=llvm-v0
Initialized environment in 144.3ms
Welcome to the CompilerGym Shell!
---------------------------------
Type help or ? for more information.
The 'tutorial' command will give a step by step guide.

compiler_gym:cbench-v1/qsort> help

Documented commands (type help <topic>):
========================================
action       help               list_rewards     set_default_observation
back         hill_climb         observation      set_default_reward
breakpoint   list_actions       require_dataset  simplify_stack
commandline  list_benchmarks    reset            stack
exit         list_datasets      reward           try_all_actions
greedy       list_observations  set_benchmark    tutorial

```

--------------------------------

### Get Current Benchmark

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/getting-started.ipynb

Access `env.benchmark` to see the name of the program currently being compiled by the environment.

```python
env.benchmark
```

--------------------------------

### Get Observation Space Shape

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/getting-started.ipynb

Retrieve the shape of the observation space, indicating the dimensionality of the state representation.

```python
env.observation_space.shape
```

--------------------------------

### Get Additional Information

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/getting-started.ipynb

Retrieves a dictionary containing additional information about the environment's state or the last step.

```python
info
```

--------------------------------

### Run GCC Autotuning Experiments

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/gcc_autotuning/README.md

Invoke the tuning script to run autotuning experiments and log results. Specify GCC binary, benchmarks, search type, budget, and repetitions.

```bash
python -m gcc_autotuning.tune <arguments>
```

--------------------------------

### Get Number of Actions

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/getting-started.ipynb

Determine the total number of discrete actions available in the environment's action space.

```python
env.action_space.n
```

--------------------------------

### Get CPU Information

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/llvm/index.md

Access essential performance information about the host CPU. This data is independent of the compiler and program state.

```python
>>> env.observation["CpuInfo"]
{'cores_count': 8, 'l1d_cache_count': 8, ...}
```

--------------------------------

### Get Observation Space Data Type

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/getting-started.ipynb

Check the data type of the observation space to understand the format of the state observations.

```python
env.observation_space.dtype
```

--------------------------------

### Reproduce LLVM Autotuning Experiments

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/llvm_autotuning/README.md

Run the main LLVM autotuning experiments by setting the AUTOTUNER and TARGET environment variables and executing the tune script. This is used to reproduce results from Section VII.C of the paper.

```sh
export AUTOTUNER=greedy; export TARGET=codesize; \
python -m llvm_autotuning.tune -m \
    experiment="$AUTOTUNER-${TARGET}" \
    autotuner="$AUTOTUNER" \
    autotuner.optimization_target="$TARGET"
```

--------------------------------

### Get Current GCC Choices

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Retrieve the current state of all optimization settings as a list of integers. This reflects the active command-line arguments.

```python
>>> env.observation["choices"]
[4, 0, -1, -1, ...]
```

--------------------------------

### Get Raw Instruction Counts (Dictionary)

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/llvm/index.md

Retrieves the raw instruction counts as a dictionary. This format provides human-readable keys for each instruction type.

```python
>>> env.observation["InstCountDict"]
{'TotalInstsCount': 406198, 'TotalBlocksCount': 46981, 'TotalFuncsCount':
3795, 'RetCount': 3712, 'BrCount': 41629, 'SwitchCount': 1489,
'IndirectBrCount': 0, 'InvokeCount': 0, 'ResumeCount': 0,
'UnreachableCount': 151, 'CleanupRetCount': 0, 'CatchRetCount': 0,
'CatchSwitchCount': 0, 'CallBrCount': 0, 'FNegCount': 49, 'AddCount': 5393,
'FAddCount': 301, 'SubCount': 3548, 'FSubCount': 157, 'MulCount': 1132,
'FMulCount': 748, 'UDivCount': 152, 'SDivCount': 296, 'FDivCount': 270,
'URemCount': 42, 'SRemCount': 72, 'FRemCount': 0, 'ShlCount': 1228,
'LShrCount': 408, 'AShrCount': 1251, 'AndCount': 2433, 'OrCount': 878,
'XorCount': 1022, 'AllocaCount': 22963, 'LoadCount': 107948, 'StoreCount':
53284, 'GetElementPtrCount': 59136, 'FenceCount': 0, 'AtomicCmpXchgCount':
0, 'AtomicRMWCount': 0, 'TruncCount': 2815, 'ZExtCount': 7711, 'SExtCount':
3082, 'FPToUICount': 14, 'FPToSICount': 327, 'UIToFPCount': 16,
'SIToFPCount': 566, 'FPTruncCount': 328, 'FPExtCount': 888, 'PtrToIntCount':
844, 'IntToPtrCount': 0, 'BitCastCount': 32345, 'AddrSpaceCastCount': 0,
'CleanupPadCount': 0, 'CatchPadCount': 0, 'ICmpCount': 14341, 'FCmpCount':
682, 'PHICount': 1622, 'CallCount': 30668, 'SelectCount': 257,
'UserOp1Count': 0, 'UserOp2Count': 0, 'VAArgCount': 0,
'ExtractElementCount': 0, 'InsertElementCount': 0, 'ShuffleVectorCount': 0,
'ExtractValueCount': 0, 'InsertValueCount': 0, 'LandingPadCount': 0,
'FreezeCount': 0}
```

--------------------------------

### Create GCC Environment with Docker Image

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Instantiate a GCC environment using a specified Docker image.

```python
import compiler_gym
env = compiler_gym.make("gcc-v0", gcc_bin="docker:gcc:11.2.0")
```

--------------------------------

### Print and Compare Autotuning Results

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/gcc_autotuning/README.md

Use the info.py script to print autotuning results for comparison against paper tables.

```bash
python -m gcc_autouning.info
```

--------------------------------

### Define another Python test target

Source: https://github.com/facebookresearch/compilergym/blob/development/tests/views/CMakeLists.txt

Configures a separate Python test executable. This example shows a different test target with its own source file and dependencies.

```cmake
cg_py_test(
  NAME
    reward_test
  SRCS
    "reward_test.py"
  DEPS
    compiler_gym::views::views
    tests::test_main
)
```

--------------------------------

### Create LLVM Autophase Environment

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/getting-started.ipynb

Creates an instance of the 'llvm-autophase-ic-v0' environment. This environment is used for the tutorial and involves LLVM compilation with Autophase observation and IR instruction count reward.

```python
env = gym.make("llvm-autophase-ic-v0")
```

--------------------------------

### Set GCC Choices

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Modify the current GCC optimization settings by providing a new list of choices. This example sets all options to their missing state (-1).

```python
>>> env.choices = [-1] * len(env.gcc_spec.options)
>>> env.choices
[-1, -1, -1, -1, ...]
```

--------------------------------

### Get Raw Instruction Counts (Array)

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/llvm/index.md

Retrieves the raw instruction counts as a NumPy array. This observation provides a detailed breakdown of various instruction types.

```python
>>> env.observation["InstCount"]
array([406198,  46981,   3795,   3712,  41629,   1489,      0,      0,
            0,    151,      0,      0,      0,      0,     49,   5393,
          301,   3548,    157,   1132,    748,    152,    296,    270,
           42,     72,      0,   1228,    408,   1251,   2433,    878,
         1022,  22963, 107948,  53284,  59136,      0,      0,      0,
         2815,   7711,   3082,     14,    327,     16,    566,    328,
          888,    844,      0,  32345,      0,      0,      0,  14341,
          682,   1622,  30668,    257,      0,      0,      0,      0,
            0,      0,      0,      0,      0,      0])
```

--------------------------------

### Inspect Environment Attributes

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/rllib.ipynb

Creates an instance of the defined environment and prints its action space, observation space, and reward space. This is a verification step.

```python
with make_env() as env:
    print("Action space:", env.action_space)
    print("Observation space:", env.observation_space)
    print("Reward space:", env.reward_space)
```

--------------------------------

### Accessing Instruction Counts Observation

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/envs/gcc.md

Illustrates how to get a dictionary of instruction counts from the assembly code. The environment first assembles the code and then counts each instruction type.

```python
>>> env.observation["instruction_counts"]
{'.file': 1, '.text': 4, '.globl': 110, '.bss': 8, '.align': 95,
 '.type': 110, '.size': 110, '.zero': 83, '.section': 10, '.long': 502,
 '.cfi': 91, 'pushq': 16, 'movq': 150, 'movl': 575, 'cmpl': 30, 'js': 7,
 'jmp': 24, 'negl': 5, 'popq': 11, 'ret': 15, 'subq': 15, 'leaq': 40,
 'movslq': 31, 'cltq': 67, 'imulq': 27, 'addq': 17, 'addl': 44, 'jle': 21,
 'sarq': 20, 'call': 34, 'subl': 7, 'sarl': 9, 'testl': 1, 'cmovns': 2,
 'jge': 3, 'sall': 2, 'orl': 1, 'leave': 4, 'andl': 2, 'nop': 7, 'cmpq': 1,
 'salq': 7, 'jns': 2, 'jne': 1, 'testq': 4, 'negq': 1, 'shrl': 2,
 '.string': 1, 'je': 2, '.ident': 1}
```

--------------------------------

### Take a Step in the Environment

Source: https://github.com/facebookresearch/compilergym/blob/development/examples/getting-started.ipynb

Executes an action in the environment and returns the new observation, reward, done status, and additional info. The action is specified by an integer.

```python
observation, reward, done, info = env.step(0)
```

--------------------------------

### Get Python Wheel Filename

Source: https://github.com/facebookresearch/compilergym/blob/development/compiler_gym/CMakeLists.txt

Executes the constructed Python package build command with the --get-wheel-filename option to determine the name of the wheel file that will be generated.

```cmake
string(CONCAT _CMD_GET_WHEEL_FILENAME "${_CMD}" " --get-wheel-filename")
execute_process(
    COMMAND bash -c "${_CMD_GET_WHEEL_FILENAME}"
    OUTPUT_VARIABLE _PY_PGK_FILE_NAME
    COMMAND_ERROR_IS_FATAL ANY
)
```

--------------------------------

### Inst2vec Embedding Vectors Example

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/llvm/index.md

Illustrates the Inst2vec observation space, which outputs np.array of 200-D embedding vectors for LLVM statements. This can be fed into an LSTM for program embedding.

```pycon
>>> env.observation["Inst2vec"]
array([[-0.26956588,  0.47407162, -0.36637706, ..., -0.49256894,
         0.8016193 ,  0.71160674],
       [-0.59749085,  0.63315004, -0.0308373 , ...,  0.14833118,
         0.86420786,  0.44808227],
       [-0.59749085,  0.63315004, -0.0308373 , ...,  0.14833118,
         0.86420786,  0.44808227],
       ...,
       [-0.37584195,  0.43671703, -0.5360456 , ...,  0.6030259 ,
         0.82574934,  0.6306344 ],
       [-0.59749085,  0.63315004, -0.0308373 , ...,  0.14833118,
         0.86420786,  0.44808227],
       [-0.43074277,  0.8589559 , -0.35770646, ...,  0.28785184,
         0.8492773 ,  0.8914213 ]], dtype=float32)
```

--------------------------------

### Run CompilerGym with Custom LLVM Bitcode Benchmark

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/llvm/index.md

Execute CompilerGym's random search tool with a custom LLVM bitcode file specified via the --benchmark flag. Ensure the correct environment name is used.

```bash
$ bazel run -c opt //compiler_gym/bin:random_search -- \
    --env=llvm-ic-v0 \
    --benchmark=file:///$PWD/myapp.bc
```

--------------------------------

### Inst2vec Preprocessed Text Example

Source: https://github.com/facebookresearch/compilergym/blob/development/docs/source/llvm/index.md

Shows the output of the Inst2vecPreprocessedText observation space, which provides a list of pre-processed LLVM statements. This is useful for normalizing IR before custom embedding.

```pycon
>>> env.observation["Inst2vecPreprocessedText"]
['opaque = type opaque', ..., 'ret i32 <%ID>']
```