1# Compiler Explorer
2
3This doc describes how to run a local instance of Compiler Explorer
4(https://godbolt.org/) with local compilers built from an Android source tree.
5
6## Prerequisites
7
8- Compiler Explorer depends on Node.js. You can download it through
9  [Node Version Manager (NVM)](https://nodejs.org/en/download/package-manager) or
10  through your favorite package manager.
11- You need a **full** Android source tree to build compilers.
12
13## Instructions
14
151. Set a directory to install Compiler Explorer.
16
17    ```
18    export COMPILER_EXPLORER_DIR=/tmp/compiler-explorer
19    ```
20
211. Create the directory.
22
23    ```
24    mkdir -p $COMPILER_EXPLORER_DIR
25    ```
26
271. Check out Compiler Explorer.
28
29    ```
30    cd $COMPILER_EXPLORER_DIR
31    git clone https://github.com/compiler-explorer/compiler-explorer.git
32    ```
33
341. Go to a full Android source tree, and initialize the environment as usual.
35
36    ```
37    cd <path-to-android-source-tree>
38    source build/envsetup.sh
39    lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
40    ```
41
42    Note: You may use a different `lunch` target, as long as it can build the
43    host binaries in the later steps.
44
451. Configure Compiler Explorer.
46
47    ```
48    cp art/tools/compiler-explorer/config/* $COMPILER_EXPLORER_DIR/compiler-explorer/etc/config
49    # Replace {{compilersDir}} in the config files with the actual path.
50    find $COMPILER_EXPLORER_DIR/compiler-explorer/etc/config -type f -name '*local*' | \
51      xargs sed -i 's?{{compilersDir}}?'$COMPILER_EXPLORER_DIR/compilers'?'
52    ```
53
541. Build Compiler Explorer.
55
56    ```
57    (cd $COMPILER_EXPLORER_DIR/compiler-explorer && make prebuild)
58    ```
59
601. Build and copy compilers except dex2oat.
61
62    ```
63    m r8 smali-baksmali
64    rm -rf $COMPILER_EXPLORER_DIR/compilers
65    mkdir $COMPILER_EXPLORER_DIR/compilers
66    cp -r prebuilts/jdk/jdk21/linux-x86 $COMPILER_EXPLORER_DIR/compilers/java-local
67    cp -r external/kotlinc $COMPILER_EXPLORER_DIR/compilers/kotlinc-local
68    mkdir $COMPILER_EXPLORER_DIR/compilers/d8-local
69    cp out/host/linux-x86/framework/r8.jar $COMPILER_EXPLORER_DIR/compilers/d8-local
70    chmod +x $COMPILER_EXPLORER_DIR/compilers/d8-local/r8.jar
71    mkdir $COMPILER_EXPLORER_DIR/compilers/baksmali-local
72    cp out/host/linux-x86/framework/smali-baksmali.jar $COMPILER_EXPLORER_DIR/compilers/baksmali-local
73    ```
74
75    Note: `smali-baksmali` is for decompiling dex code. You don't need it if you
76    only want to see native code generated by dex2oat.
77
781. Build and copy dex2oat.
79
80    ```
81    m dist out/dist/art_release.zip
82    rm -rf $COMPILER_EXPLORER_DIR/compilers/dex2oat-local
83    unzip -d $COMPILER_EXPLORER_DIR/compilers/dex2oat-local out/dist/art_release.zip
84    ```
85
86    Note: You may choose to do this on `master-art` instead of on a full Android
87    source tree if you wish.
88
891. Generate boot images (optional but recommended).
90
91    ```
92    declare -a instruction_sets=("arm" "arm64" "x86" "x86_64" "riscv64")
93    m generate-boot-image
94    rm -rf $COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app
95    mkdir -p $COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app/apex/com.android.art/javalib
96    cp $COMPILER_EXPLORER_DIR/compilers/dex2oat-local/bootjars/* \
97        $COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app/apex/com.android.art/javalib
98    mkdir -p $COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app/system/framework
99    for instruction_set in "${instruction_sets[@]}"; do
100      $ANDROID_HOST_OUT/bin/generate-boot-image64 \
101          --output-dir=$COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app/system/framework \
102          --compiler-filter=speed \
103          --use-profile=false \
104          --dex2oat-bin=$COMPILER_EXPLORER_DIR/compilers/dex2oat-local/x86_64/bin/dex2oat64 \
105          --android-root=$COMPILER_EXPLORER_DIR/compilers/dex2oat-local/app \
106          --core-only=true \
107          --instruction-set=$instruction_set \
108          -- \
109          --runtime-arg \
110          -Xgc:CMC
111    done
112    ```
113
114    Note: You may change `instruction_sets` on the first line to only include
115    the instruction sets that you need, to speed up boot image generation.
116
117    Note: Although this step is not required, having boot images makes dex2oat generate better code.
118
1191. Start Compiler Explorer server.
120
121    ```
122    (cd $COMPILER_EXPLORER_DIR/compiler-explorer && make run-only)
123    ```
124
125    Once you see `Listening on http://localhost:10240/`, you can open a browser
126    with that address to access Compiler Explorer.
127
128When you iterate, press `Ctrl+C` to stop the server, and then repeat the last
129three steps.
130