xref: /aosp_15_r20/art/tools/compiler-explorer/compiler-explorer.md (revision 795d594fd825385562da6b089ea9b2033f3abf5a)

# Compiler Explorer

This doc describes how to run a local instance of Compiler Explorer
(https://godbolt.org/) with local compilers built from an Android source tree.

## Prerequisites

- Compiler Explorer depends on Node.js. You can download it through
  [Node Version Manager (NVM)](https://nodejs.org/en/download/package-manager) or
  through your favorite package manager.
- You need a **full** Android source tree to build compilers.

## Instructions

1. Set a directory to install Compiler Explorer.

    ```
    export COMPILER_EXPLORER_DIR=/tmp/compiler-explorer
    ```

1. Create the directory.

    ```
    mkdir -p $COMPILER_EXPLORER_DIR
    ```

1. Check out Compiler Explorer.

    ```
    cd $COMPILER_EXPLORER_DIR
    git clone https://github.com/compiler-explorer/compiler-explorer.git
    ```

1. Go to a full Android source tree, and initialize the environment as usual.

    ```
    cd <path-to-android-source-tree>
    source build/envsetup.sh
    lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
    ```

    Note: You may use a different `lunch` target, as long as it can build the
    host binaries in the later steps.

1. Configure Compiler Explorer.

    ```
    cp art/tools/compiler-explorer/config/* $COMPILER_EXPLORER_DIR/compiler-explorer/etc/config
    # Replace {{compilersDir}} in the config files with the actual path.
    find $COMPILER_EXPLORER_DIR/compiler-explorer/etc/config -type f -name '*local*' | \
      xargs sed -i 's?{{compilersDir}}?'$COMPILER_EXPLORER_DIR/compilers'?'
    ```

1. Build Compiler Explorer.

    ```
    (cd $COMPILER_EXPLORER_DIR/compiler-explorer && make prebuild)
    ```

1. Build and copy compilers except dex2oat.

    ```
    m r8 smali-baksmali
    rm -rf $COMPILER_EXPLORER_DIR/compilers
    mkdir $COMPILER_EXPLORER_DIR/compilers
    cp -r prebuilts/jdk/jdk21/linux-x86 $COMPILER_EXPLORER_DIR/compilers/java-local
    cp -r external/kotlinc $COMPILER_EXPLORER_DIR/compilers/kotlinc-local
    mkdir $COMPILER_EXPLORER_DIR/compilers/d8-local
    cp out/host/linux-x86/framework/r8.jar $COMPILER_EXPLORER_DIR/compilers/d8-local
    chmod +x $COMPILER_EXPLORER_DIR/compilers/d8-local/r8.jar
    mkdir $COMPILER_EXPLORER_DIR/compilers/baksmali-local
    cp out/host/linux-x86/framework/smali-baksmali.jar $COMPILER_EXPLORER_DIR/compilers/baksmali-local
    ```

    Note: `smali-baksmali` is for decompiling dex code. You don't need it if you
    only want to see native code generated by dex2oat.

1. Build and copy dex2oat.

    ```
    m dist out/dist/art_release.zip
    rm -rf $COMPILER_EXPLORER_DIR/compilers/dex2oat-local
    unzip -d $COMPILER_EXPLORER_DIR/compilers/dex2oat-local out/dist/art_release.zip
    ```

    Note: You may choose to do this on `master-art` instead of on a full Android
    source tree if you wish.

1. Generate boot images (optional but recommended).

    ```
    declare -a instruction_sets=("arm" "arm64" "x86" "x86_64" "riscv64")
    m generate-boot-image
    rm -rf $COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app
    mkdir -p $COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app/apex/com.android.art/javalib
    cp $COMPILER_EXPLORER_DIR/compilers/dex2oat-local/bootjars/* \
        $COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app/apex/com.android.art/javalib
    mkdir -p $COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app/system/framework
    for instruction_set in "${instruction_sets[@]}"; do
      $ANDROID_HOST_OUT/bin/generate-boot-image64 \
          --output-dir=$COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app/system/framework \
          --compiler-filter=speed \
          --use-profile=false \
          --dex2oat-bin=$COMPILER_EXPLORER_DIR/compilers/dex2oat-local/x86_64/bin/dex2oat64 \
          --android-root=$COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app \
          --core-only=true \
          --instruction-set=$instruction_set \
          -- \
          --runtime-arg \
          -Xgc:CMC
    done
    ```

    Note: You may change `instruction_sets` on the first line to only include
    the instruction sets that you need, to speed up boot image generation.

    Note: Although this step is not required, having boot images makes dex2oat generate better code.

1. Start Compiler Explorer server.

    ```
    (cd $COMPILER_EXPLORER_DIR/compiler-explorer && make run-only)
    ```

    Once you see `Listening on http://localhost:10240/`, you can open a browser
    with that address to access Compiler Explorer.

When you iterate, press `Ctrl+C` to stop the server, and then repeat the last
three steps.