Frequently Asked Questions¶

This page answers some of the commonly asked questions about CompilerGym. Have a question not answered here? File an issue on the GitHub issue tracker.

Topics:

General
LLVM Environment
Development

This projects lets you control the decisions that a compiler makes when optimizing a program. Currently, it lets you control the selection and ordering of optimization passes for LLVM in order to minimize the size of the code.

We wrote a small wrapper around the OpenAI gym environment which lets you step through the optimization of a program using a text user interface. Have a play around with it to better understand what is going on:

$ python -m compiler_gym.bin.manual_env --env=llvm-v0

Once you get the hang of things, try submitting your best algorithm to our leaderboards!

Do I have to use reinforcement learning?¶

No. We think that the the gym provides a useful abstraction for sequential decision making. You may use any technique you wish to explore the optimization space.

What features are going to be added in the future?¶

See roadmap.

Is compiler optimization really a sequential decision process?¶

Compilers frequently package individual transformations as “optimization passes” which are then applied in a sequential order. Usually this order is fixed (e.g. real world example). CompilerGym replaces that fixed order with a sequential decision process where any pass may be applied at any stage.

LLVM Environment ¶

When does the environment consider an episode “done”?¶

The compiler itself doesn’t have a signal for termination. Actions are like rewrite rules, it is up to the user to decide when no more improvement can be achieved from further rewrites. E.g. for simple random search we can use “patience”. The only exception is if the compiler crashes, or the code ends up in an unexpected state - we have to abort. This happens.

How do I run this on my own program?¶

By compiling your program to an unoptimized LLVM bitcode file. This can be done automatically for C/C++ programs using the env.make_benchmark() API, or you can do this yourself using clang:

$ clang -emit-llvm -c -O0 -Xclang -disable-O0-optnone -Xclang -disable-llvm-passes myapp.c

Then pass the path of the generated .bc file to the CompilerGym command-line tools using the –benchmark flag, e.g.

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

Should I always try different actions?¶

Some optimization actions may be called multiple times after other actions. An example of this is dead code elimination, which can be used to “clean up mess” generated from a previous action. So repeating the same action in different context can bring improvements.

Development ¶

I found a bug. How do I report it?¶

Great! Please file an issue using the GitHub issue tracker. See Contributing for more details.

I updated with “git pull” and now it doesn’t work ¶

The first thing to is to re-run make init to ensure that you have the correct development dependencies installed, as those can change between releases. Then run make distclean to tidy up any build artifacts from the old version.

If that doesn’t fix the problem, feel free to file an issue, but note that the development branch is the bleeding edge and may contain features that have not yet reached stability. If you would like to build from source but do not require the latest feature set, use the stable branch which lags to the latest release with hotfixes.

I want to add a new program representation / reward signal. How do I do that?¶

If your reward or observation is a transformation of an existing space, consider using the compiler_gym.wrappers module to define a wrapper that performs the translation from the base space.

If your reward or observation requires combining multiple existing spaces, consider using add_derived_space() or add_space().

If you require modifying the underlying compiler service implementation, fork this project and build it from source (see installation). Then modify the service implementation for the compiler that you are interested in. The service codebase is located at compiler_gym/envs/$COMPILER/service, where $COMPILER is the name of the compiler service you would wish to modify, e.g. llvm. Once done, send us a pull request!