In the Compilation sandbox, decomp.me uses specific colors and symbols to denote differences between Target and Current assembly code:

• Branches (~>): Color-coded to form "from" and "to" pairs.
• Registers: Registers used in the same context are equivalently color-coded between Target and Current to help spot usage.

Difference Indicators

The project supports running subprocesses within a secure jail using nsjail. This is controlled via SANDBOX settings. By default, sandboxing is disabled in the development .env file, but it is enabled within the backend Docker container. To enable it for local development outside of Docker, you must install nsjail locally, configure kernel unprivileged user namespaces, and update your environment configuration.

### 1. Install nsjail (Ubuntu example)
```bash
apt-get install autoconf bison flex gcc g++ git libprotobuf-dev libnl-route-3-dev libtool make pkg-config protobuf-compiler
git clone --recursive --branch=3.0 https://github.com/google/nsjail
cd nsjail && make

2. Enable unprivileged_userns_clone

Temporary:

sudo sysctl -w kernel.unprivileged_userns_clone=1

Permanent:

echo 'kernel.unprivileged_userns_clone=1' | sudo tee -a /etc/sysctl.d/00-local-userns.conf && sudo service procps restart

3. Configure .env.local

Set USE_SANDBOX_JAIL to 'on'

Set SANDBOX_NSJAIL_BIN_PATH to the absolute path of your nsjail binary

To add a new compiler to the decomp.me ecosystem, you must register it across the compilers repository, the backend, and the frontend. Ensure the compiler key is consistent across the backend definition, the downloaded compiler configuration, and the frontend display name.

Checklist for adding a compiler:

1. Compiler Package: Raise a PR to add the compiler package to the decompme/compilers repository.
2. Backend Installation: Add an entry to backend/compilers/compilers.linux.yaml so the backend can download and install the compiler.
3. Backend Definition: Add the compiler definition to backend/coreapp/compilers.py:
   • Provide the command used to run the compiler.
   • Add the compiler to the _all_compilers list.
4. Frontend Localization: Add a user-friendly compiler name to frontend/src/lib/i18n/locales/en/compilers.json.
5. Flags (Optional): If the compiler requires new flags, add them to backend/coreapp/flags.py.
6. Verification: Test the integration to ensure it works as expected.

To work with real production data for testing migrations or debugging, you can spin up a local copy of the database using Docker.

Prerequisites

1. Fresh Data Directory: The restore process requires an empty local Postgres data directory. In this repository, that directory is ./postgres. If it already exists, move it out of the way before starting.
2. Backup Files: You need two specific files (typically obtained from the decomp.me Discord):
   • A main anonymized database dump (e.g., decompme_public_*.backup).
   • An anonymized user CSV (e.g., coreapp_user_*.csv) to satisfy foreign keys.
3. Placement: Place both files in the ./pgdump directory at the base of the repository. This directory is mounted to /pgdump inside the container.

Restore Steps

1. Start the Postgres container:

   docker compose up -d postgres

2. Enter the container and switch to the postgres user:

   docker compose exec -ti postgres bash
   su - postgres

3. Restore the main dump using pg_restore. You can increase --jobs to match your CPU cores to speed up the process:

   pg_restore -U decompme -d decompme --verbose --jobs=4 /pgdump/decompme_public_*.backup

4. Restore the auth_user table from the CSV file:

   psql -U decompme -d decompme \
     -c "\copy auth_user (id, password, last_login, is_superuser, username, first_name, last_name, email, is_staff, is_active, date_joined) \
       FROM '/pgdump/coreapp_user_*.csv' WITH CSV HEADER"

5. Reset the auth_user ID sequence to prevent primary key collisions when creating new local users:

   psql -U decompme -d decompme \
     -c "SELECT setval(pg_get_serial_sequence('auth_user', 'id'), COALESCE(MAX(id), 1)) FROM auth_user;"

6. (Optional) Start the rest of the stack:

   docker compose up -d

# Summary of the restore sequence
docker compose up -d postgres
docker compose exec -ti postgres bash
su - postgres
pg_restore -U decompme -d decompme --verbose --jobs=4 /pgdump/decompme_public_*.backup
psql -U decompme -d decompme -c "\copy auth_user (...) FROM '/pgdump/coreapp_user_*.csv' WITH CSV HEADER"
psql -U decompme -d decompme -c "SELECT setval(pg_get_serial_sequence('auth_user', 'id'), COALESCE(MAX(id), 1)) FROM auth_user;"