criu/.github/copilot-instructions.md

GitHub Copilot Instructions for CRIU

CRIU (Checkpoint/Restore In User-space) is a specialized tool for checkpointing and restoring running processes on Linux.

Coding Style & Conventions

All C code MUST follow the Linux Kernel Coding Style.

• Indentation: Use hard tabs. Set tab width to 8 characters.
• Line Length: Preferred limit is 80 characters. Max 120 if it significantly improves readability.
• Braces:
  • Functions: Opening brace on a new line.
  • Blocks (if, for, while, switch): Opening brace on the same line as the statement.
• Spaces: Use spaces around operators (+, -, *, /, %, <, >, =, etc.).
• Naming: Use descriptive, snake_case names for functions and variables.
• Comments: Use C-style comments (/* ... */).
  • Multi-line format:

    /*
     * This is a multi-line
     * comment.
     */
    

Architecture Overview

• criu/: Contains the main logic for checkpoint and restore.
• compel/: Sub-project for "parasite" code injection and PIE blob generation.
• images/: Protobuf descriptions for image files. Use these to understand the state being saved.
• restorer: PIE code that handles the final stages of process restoration. See criu/include/restorer.h for CR_STATE_* definitions.
• crit: Tooling for inspecting CRIU image files.
• soccr: Library for TCP socket checkpoint/restore.
• pie/ directories: Code in these directories (e.g., criu/pie/) should be self-contained Position-Independent Executable (PIE) code. It MUST NOT depend on any external libraries and can only depend on things implemented by Compel.

CRIU Commands

• dump: Saves a process tree and all its related resources into a collection of image files.
• restore: Restores processes from image files to the same state they were in before the dump.
• check: Checks whether the kernel supports the features needed by CRIU to dump and restore a process tree.
• pre-dump: Performs the pre-dump procedure, creating a snapshot of memory changes since the previous dump/pre-dump (incremental checkpointing).
• service: Launches CRIU in RPC daemon mode, listening for commands over a socket.
• dedup: Starts pagemap data deduplication, minimizing image size by obtaining references from parent images.
• page-server: Launches CRIU in page server mode to send memory pages over the network during migration.

Development & Testing

• ZDTM (Zero-Downtime Migration): The primary test suite located in test/zdtm.
• Test Scope: Each test case targets a specific kernel primitive type (e.g., file descriptors, sockets, timers).
• Test Purpose: Verifies that the targeted kernel primitive is Checkpointed/Restored (C/R-ed) correctly.
• Test Executor: test/zdtm.py.
• Running a test: sudo ./test/zdtm.py run -t zdtm/static/env00.
• Test Structure: Tests typically use test_daemon() to signal readiness and test_waitsig() to wait for the C/R cycle to complete. After being restored, the test checks that all its resources are still in a valid state.

Commit Message Guidelines

Follow these principles when forming commits:

• Separate each logical change into a separate patch: Each commit must represent a single logical change. Separate bug fixes from performance improvements or API updates.
• The commit subject has to start with the sub-system prefix: Prefix the subject with the affected component (e.g., criu:, compel:, images:, test:, or specific file names like criu-ns:).
• Imperative Mood: Use the imperative mood in the subject (e.g., "make xyzzy do frotz" instead of "changed xyzzy").
• Detailed Body: Explain the problem being solved (the "why") and the technical details of the implementation (the "how").
• Hard Wrap: The commit message has to be hard wrapped at 72 characters.
• Signed-off-by: Every commit MUST be signed off (git commit -s). This certifies the Developer's Certificate of Origin (DCO).
• Fixes Tag:
  • For bugs: Fixes: <12-char-commit-id> ("summary"). The <commit-id> has to be the first 12 characters of the commit SHA-1 ID.
  • For GitHub issues: Fixes: #<issue-number>
• Atomicity: Ensure CRIU builds and tests pass after every commit in a series to maintain bisectability.
• No Fixups: Squash "fixup!" or "work in progress" commits before final submission.