Two files, one repository
topjohnwu/Magisk ships 1 format across 3 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 9 | 0% |
| Commands | 0 | 3 | 0 | 0% |
| Section tags | 4 | 2 | 3 | 44% |
What each file covers
Sections
0 shared · 5 only in A · 9 only in B- − AGENTS.md
- − 1. Environment & Execution Setup
- − 2. Codebase Structure & Architecture
- − 3. Build & Verification Workflows
- − 4. Guidelines for AI Models
- + AGENTS.md (native subproject)
- + 1. Environment & Build Requirements
- + 2. Component Architecture
- + Key Native Binary Output Targets
- + 3. Build System Orchestration
- + 4. FFI Architecture & Mechanics
- + 5. Build Targets & Commands (from Root)
- + 6. Rust & C++ Conventions
- + 7. Magisk Rust Patterns & Non-Standard Idioms
Commands
0 shared · 3 only in A · 0 only in B- − ./gradlew
- − cargo
- − rustc
Section tags
4 shared · 2 only in A · 3 only in B- − architecture
- − git-pr
- + test
- + code-style
- + ui
- setup
- build
- lint-format
- do-not
Line diff
topjohnwu/Magisk · AGENTS.md
@@ −1 @@
1# AGENTS.md
2
3Guidelines and instructions for AI models and automated agents operating in the Magisk repository.
4
5## 1. Environment & Execution Setup
6
7- **`build.py` Invocations:** `./build.py` imports `scripts/env.py` internally and configures the environment automatically. It does **not** need to be prefixed with `scripts/env.py` (e.g., `./build.py all` or `./build.py native`).
8- **Direct Tool Executions:** Standalone commands outside of `build.py` (such as `./gradlew`, `cargo`, `rustc`, `ndk-build`, etc.) **MUST** be prefixed with `scripts/env.py` (e.g., `scripts/env.py ./gradlew assembleDebug`).
9- **NDK Toolchain Setup:** If NDK toolchain dependencies are missing or outdated, run `./build.py ndk`.
10
11## 2. Codebase Structure & Architecture
12
13- **`app/` (Android Application):** Multi-module Gradle project for the Android app. Refer to [`app/AGENTS.md`](app/AGENTS.md) for app architecture, submodules, Kotlin conventions, and Gradle workflows.
14- **`native/` (Native Core Binaries):** C, C++, and Rust codebase for building native components (`magisk`, `magiskinit`, `magiskboot`, `magiskpolicy`, `resetprop`). Refer to [`native/AGENTS.md`](native/AGENTS.md) for native architecture, submodules, FFI compilation, and Rust conventions.
15- **`build.py` (Primary Build Orchestrator):** Python script managing native builds, app packaging, Clippy runs, Cargo invocations, and cleanup.
16- **`tools/` & `scripts/`:** Build scripts, helper utilities (e.g., `elf-cleaner`), and environment setup tools.
17
18## 3. Build & Verification Workflows
19
20- **Build Complete Project (APK + Native):** `./build.py all`
21- **Build Native Components:** `./build.py native [target...]`
22- **Build Application Targets:** `./build.py app`, `./build.py stub`, `./build.py test`
23- **Rust Verification & Linting:** `./build.py clippy`, `./build.py cargo <cargo-commands...>`
24- **Clean Build Artifacts:** `./build.py clean [native|cpp|rust|java|app]`
25
26## 4. Guidelines for AI Models
27
281. **Git / Commit Control:** NEVER commit changes or amend an existing git commit without the user's explicit request or approval. When explicitly requested to commit changes, follow the 50/72 rule for commit messages (subject line <= 50 characters, blank line before body, wrap body lines at 72 characters) and include an `Assisted-by: <ModelVersion>` trailer in the commit message body (using a pretty name, e.g., `Assisted-by: Gemini 3.6 Flash`).
292. **Build Invocation:** Execute `./build.py <command>` directly without `scripts/env.py`. Prefix standalone tool executions (like `./gradlew` or raw `cargo`) with `scripts/env.py`.
303. **Pre-build Native Code:** Before modifying code in `native/`, build native binaries at least once with `./build.py native` to generate required bindings and header files.
314. **App Subproject Context:** Refer to [`app/AGENTS.md`](app/AGENTS.md) when working inside the `app/` subproject.
325. **Verification Loop:** After making changes, verify compilation and run linting/clippy checks for affected modules before concluding tasks.
33
topjohnwu/Magisk · native/AGENTS.md
@@ +1 @@
1# AGENTS.md (native subproject)
2
3Guidelines for AI models operating inside the `native/` subproject.
4
5## 1. Environment & Build Requirements
6
7- **Working Directory:** Execute commands from repo root via `./build.py`.
8- **Pre-build Requirement:** ALWAYS run `./build.py native` at least once before editing native sources to generate FFI bindings, headers, and flags (`flags.h`, `flags.rs`, `*-rs.hpp`, `*-rs.cpp`, protobuf generated modules).
9
10## 2. Component Architecture
11
12Native C, C++, and Rust source modules under `native/src/`:
13- **`base/`**: System wrappers, logging, custom string abstractions (`Utf8CStr`), mount helpers, and common utilities (C++/Rust).
14- **`boot/`**: Boot image parsing, unpacking, repacking, and ramdisk patching logic (`magiskboot`) (Rust/C++).
15- **`core/`**: Magisk daemon (`magiskd`), Zygisk engine, `su` implementation, applets, and system properties (`resetprop`) (C++/Rust).
16- **`init/`**: Early boot `magiskinit`, ramdisk patching, SELinux pre-init (C/C++/Rust).
17- **`sepolicy/`**: SELinux policy engine (`libpolicy`) and `magiskpolicy` CLI (C++/Rust).
18- **`external/`**: Embedded dependencies (`cxx-rs`, `selinux`, `crt0`, `system_properties`, `lsplt`, `lz4-sys`, `xz-embedded`).
19
20### Key Native Binary Output Targets
21- `magisk`: Core daemon, Zygisk, `su`, and applets executable.
22- `magiskinit`: Early init replacement executable (static).
23- `magiskboot`: Boot image patcher executable (static).
24- `magiskpolicy`: SELinux policy tool executable.
25- `resetprop`: System property reader/writer executable.
26
27## 3. Build System Orchestration
28
29The build process follows a two-stage hybrid pipeline orchestrated by `build.py`:
30
31```
321. dump_flags_native() --> Outputs flags.h & flags.rs to native/out/generated/
332. build_rust_src() --> Cargo build outputs lib<tgt>.a for each target ABI
34 Cargo build.rs runs cxx_gen to produce *-rs.hpp / *-rs.cpp
35 Cargo build.rs runs pb-rs to generate Protobuf bindings
36 Static libraries moved to native/out/<arch>/lib<tgt>-rs.a
373. build_cpp_src() --> ndk-build runs using Android.mk & Application.mk
38 Android-rs.mk imports lib<tgt>-rs.a as PREBUILT_STATIC_LIBRARY
39 Compiles C/C++ sources + *-rs.cpp bridge files + cxx.cc
404. clean_elf() --> tools/elf-cleaner strips incompatible ELF dynamic tags
41```
42
43## 4. FFI Architecture & Mechanics
44
45- **Bridge Engine:** C++/Rust FFI uses `cxx` (`cxx-rs`) via `#[cxx::bridge]` modules declared in crate `lib.rs` files.
46- **Header & Source Generation:**
47 - `codegen.rs` (`gen_cxx_binding()`) invokes `cxx_gen` in crate `build.rs` scripts.
48 - Automatically generates C++ bridge headers (`*-rs.hpp`) and source wrappers (`*-rs.cpp`) directly in each crate directory.
49 - Generates bindings for `base-rs`, `core-rs`, `init-rs`, `boot-rs`, and `policy-rs`.
50- **Linking:** Generated `*-rs.cpp` bridge code and `cxx.cc` are compiled directly by `ndk-build` alongside native C++ source files, linking against the compiled Rust static library (`lib<tgt>-rs.a`).
51
52## 5. Build Targets & Commands (from Root)
53
54- **Build All Native Binaries:** `./build.py native`
55- **Build Specific Target(s):** `./build.py native [magisk|magiskinit|magiskboot|magiskpolicy|resetprop]`
56- **Rust Clippy Lint:** `./build.py clippy`
57- **Cargo Commands:** `./build.py cargo check`, `./build.py cargo test`
58- **Generate IDE Database:** `./build.py gen`
59- **Clean Native Artifacts:** `./build.py clean native`
60
61## 6. Rust & C++ Conventions
62
63- **Rust Edition & Profile:** Rust Edition 2024. Profile configured with `panic = "immediate-abort"` across dev and release profiles.
64- **C++ Standard:** C++20 with `libc++` static linking.
65- **Clippy Rules:** `unwrap_used = "deny"` in workspace configuration. **Do NOT use `.unwrap()` in Rust code.** Use `?`, `unwrap_or`, `unwrap_or_else`, or pattern matching.
66- **Incremental Build Protection:** File writers (`write_if_diff`) skip rewriting identical generated files to preserve compilation timestamps and avoid unnecessary rebuilds.
67
68## 7. Magisk Rust Patterns & Non-Standard Idioms
69
70AI models modifying or writing Rust code in `native/src/` MUST follow these Magisk-specific idioms:
71
721. **Custom String Handling (`Utf8CStr` & `cstr!`):**
73 - Standard C/C++ APIs require null-terminated UTF-8 strings. Do NOT create intermediate `CString` allocations.
74 - Use `&Utf8CStr` for string references, `Utf8CString` for heap buffers, and `Utf8CStrBufArr<N>` for stack buffers (`base/cstr.rs`).
75 - Use `cstr!("literal")` for compile-time null-terminated static strings.
76 - Use `StringExt::nul_terminate` for in-place null byte termination using reserved string capacity.
77
782. **Instant Logging Error Model (`LoggedError`):**
79 - Application logic does NOT use standard error enums or `anyhow`.
80 - Errors are logged immediately at the failure point via `log_err!`, `.log()`, or `.log_with_msg()` and converted into zero-sized `LoggedError` / `LoggedResult<T>`.
81 - In debug builds, `#[track_caller]` logs the file and line number of error sites automatically. Use `.silent()` to silence expected failures.
82
833. **Libc System Call Conversions (`LibcReturn`):**
84 - When calling raw libc or C system APIs in Rust or `xwrap.rs`, use `LibcReturn::into_os_result` or `check_err` to automatically map negative integer returns or null pointers into `OsResult` or `LoggedResult`.
85
864. **Zero Allocation & Binary Size Rules:**
87 - Prefer custom `argh` derivation (`base/argh.rs`) for command-line parsing instead of adding standard argument dependencies.
88 - Avoid `serde` overhead; use procedural `Encodable`/`Decodable` binary traits over UNIX domain sockets for IPC.
89
905. **Nightly Synchronization & IPC:**
91 - Magisk uses nightly features (`unix_socket_ancillary_data`, `nonpoison_mutex`).
92 - Use non-poisoning mutexes/condvars for daemon threading and `send_fd`/`recv_fd` for raw file descriptor passing.
93
@@ −1 +1 @@
1−# AGENTS.md
1+# AGENTS.md (native subproject)
22
3−Guidelines and instructions for AI models and automated agents operating in the Magisk repository.
3+Guidelines for AI models operating inside the `native/` subproject.
44
5−## 1. Environment & Execution Setup
5+## 1. Environment & Build Requirements
66
7−- **`build.py` Invocations:** `./build.py` imports `scripts/env.py` internally and configures the environment automatically. It does **not** need to be prefixed with `scripts/env.py` (e.g., `./build.py all` or `./build.py native`).
8−- **Direct Tool Executions:** Standalone commands outside of `build.py` (such as `./gradlew`, `cargo`, `rustc`, `ndk-build`, etc.) **MUST** be prefixed with `scripts/env.py` (e.g., `scripts/env.py ./gradlew assembleDebug`).
9−- **NDK Toolchain Setup:** If NDK toolchain dependencies are missing or outdated, run `./build.py ndk`.
7+- **Working Directory:** Execute commands from repo root via `./build.py`.
8+- **Pre-build Requirement:** ALWAYS run `./build.py native` at least once before editing native sources to generate FFI bindings, headers, and flags (`flags.h`, `flags.rs`, `*-rs.hpp`, `*-rs.cpp`, protobuf generated modules).
109
11−## 2. Codebase Structure & Architecture
10+## 2. Component Architecture
1211
13−- **`app/` (Android Application):** Multi-module Gradle project for the Android app. Refer to [`app/AGENTS.md`](app/AGENTS.md) for app architecture, submodules, Kotlin conventions, and Gradle workflows.
14−- **`native/` (Native Core Binaries):** C, C++, and Rust codebase for building native components (`magisk`, `magiskinit`, `magiskboot`, `magiskpolicy`, `resetprop`). Refer to [`native/AGENTS.md`](native/AGENTS.md) for native architecture, submodules, FFI compilation, and Rust conventions.
15−- **`build.py` (Primary Build Orchestrator):** Python script managing native builds, app packaging, Clippy runs, Cargo invocations, and cleanup.
16−- **`tools/` & `scripts/`:** Build scripts, helper utilities (e.g., `elf-cleaner`), and environment setup tools.
12+Native C, C++, and Rust source modules under `native/src/`:
13+- **`base/`**: System wrappers, logging, custom string abstractions (`Utf8CStr`), mount helpers, and common utilities (C++/Rust).
14+- **`boot/`**: Boot image parsing, unpacking, repacking, and ramdisk patching logic (`magiskboot`) (Rust/C++).
15+- **`core/`**: Magisk daemon (`magiskd`), Zygisk engine, `su` implementation, applets, and system properties (`resetprop`) (C++/Rust).
16+- **`init/`**: Early boot `magiskinit`, ramdisk patching, SELinux pre-init (C/C++/Rust).
17+- **`sepolicy/`**: SELinux policy engine (`libpolicy`) and `magiskpolicy` CLI (C++/Rust).
18+- **`external/`**: Embedded dependencies (`cxx-rs`, `selinux`, `crt0`, `system_properties`, `lsplt`, `lz4-sys`, `xz-embedded`).
1719
18−## 3. Build & Verification Workflows
20+### Key Native Binary Output Targets
21+- `magisk`: Core daemon, Zygisk, `su`, and applets executable.
22+- `magiskinit`: Early init replacement executable (static).
23+- `magiskboot`: Boot image patcher executable (static).
24+- `magiskpolicy`: SELinux policy tool executable.
25+- `resetprop`: System property reader/writer executable.
1926
20−- **Build Complete Project (APK + Native):** `./build.py all`
21−- **Build Native Components:** `./build.py native [target...]`
22−- **Build Application Targets:** `./build.py app`, `./build.py stub`, `./build.py test`
23−- **Rust Verification & Linting:** `./build.py clippy`, `./build.py cargo <cargo-commands...>`
24−- **Clean Build Artifacts:** `./build.py clean [native|cpp|rust|java|app]`
27+## 3. Build System Orchestration
2528
26−## 4. Guidelines for AI Models
29+The build process follows a two-stage hybrid pipeline orchestrated by `build.py`:
2730
28−1. **Git / Commit Control:** NEVER commit changes or amend an existing git commit without the user's explicit request or approval. When explicitly requested to commit changes, follow the 50/72 rule for commit messages (subject line <= 50 characters, blank line before body, wrap body lines at 72 characters) and include an `Assisted-by: <ModelVersion>` trailer in the commit message body (using a pretty name, e.g., `Assisted-by: Gemini 3.6 Flash`).
29−2. **Build Invocation:** Execute `./build.py <command>` directly without `scripts/env.py`. Prefix standalone tool executions (like `./gradlew` or raw `cargo`) with `scripts/env.py`.
30−3. **Pre-build Native Code:** Before modifying code in `native/`, build native binaries at least once with `./build.py native` to generate required bindings and header files.
31−4. **App Subproject Context:** Refer to [`app/AGENTS.md`](app/AGENTS.md) when working inside the `app/` subproject.
32−5. **Verification Loop:** After making changes, verify compilation and run linting/clippy checks for affected modules before concluding tasks.
31+```
32+1. dump_flags_native() --> Outputs flags.h & flags.rs to native/out/generated/
33+2. build_rust_src() --> Cargo build outputs lib<tgt>.a for each target ABI
34+ Cargo build.rs runs cxx_gen to produce *-rs.hpp / *-rs.cpp
35+ Cargo build.rs runs pb-rs to generate Protobuf bindings
36+ Static libraries moved to native/out/<arch>/lib<tgt>-rs.a
37+3. build_cpp_src() --> ndk-build runs using Android.mk & Application.mk
38+ Android-rs.mk imports lib<tgt>-rs.a as PREBUILT_STATIC_LIBRARY
39+ Compiles C/C++ sources + *-rs.cpp bridge files + cxx.cc
40+4. clean_elf() --> tools/elf-cleaner strips incompatible ELF dynamic tags
41+```
42+
43+## 4. FFI Architecture & Mechanics
44+
45+- **Bridge Engine:** C++/Rust FFI uses `cxx` (`cxx-rs`) via `#[cxx::bridge]` modules declared in crate `lib.rs` files.
46+- **Header & Source Generation:**
47+ - `codegen.rs` (`gen_cxx_binding()`) invokes `cxx_gen` in crate `build.rs` scripts.
48+ - Automatically generates C++ bridge headers (`*-rs.hpp`) and source wrappers (`*-rs.cpp`) directly in each crate directory.
49+ - Generates bindings for `base-rs`, `core-rs`, `init-rs`, `boot-rs`, and `policy-rs`.
50+- **Linking:** Generated `*-rs.cpp` bridge code and `cxx.cc` are compiled directly by `ndk-build` alongside native C++ source files, linking against the compiled Rust static library (`lib<tgt>-rs.a`).
51+
52+## 5. Build Targets & Commands (from Root)
53+
54+- **Build All Native Binaries:** `./build.py native`
55+- **Build Specific Target(s):** `./build.py native [magisk|magiskinit|magiskboot|magiskpolicy|resetprop]`
56+- **Rust Clippy Lint:** `./build.py clippy`
57+- **Cargo Commands:** `./build.py cargo check`, `./build.py cargo test`
58+- **Generate IDE Database:** `./build.py gen`
59+- **Clean Native Artifacts:** `./build.py clean native`
60+
61+## 6. Rust & C++ Conventions
62+
63+- **Rust Edition & Profile:** Rust Edition 2024. Profile configured with `panic = "immediate-abort"` across dev and release profiles.
64+- **C++ Standard:** C++20 with `libc++` static linking.
65+- **Clippy Rules:** `unwrap_used = "deny"` in workspace configuration. **Do NOT use `.unwrap()` in Rust code.** Use `?`, `unwrap_or`, `unwrap_or_else`, or pattern matching.
66+- **Incremental Build Protection:** File writers (`write_if_diff`) skip rewriting identical generated files to preserve compilation timestamps and avoid unnecessary rebuilds.
67+
68+## 7. Magisk Rust Patterns & Non-Standard Idioms
69+
70+AI models modifying or writing Rust code in `native/src/` MUST follow these Magisk-specific idioms:
71+
72+1. **Custom String Handling (`Utf8CStr` & `cstr!`):**
73+ - Standard C/C++ APIs require null-terminated UTF-8 strings. Do NOT create intermediate `CString` allocations.
74+ - Use `&Utf8CStr` for string references, `Utf8CString` for heap buffers, and `Utf8CStrBufArr<N>` for stack buffers (`base/cstr.rs`).
75+ - Use `cstr!("literal")` for compile-time null-terminated static strings.
76+ - Use `StringExt::nul_terminate` for in-place null byte termination using reserved string capacity.
77+
78+2. **Instant Logging Error Model (`LoggedError`):**
79+ - Application logic does NOT use standard error enums or `anyhow`.
80+ - Errors are logged immediately at the failure point via `log_err!`, `.log()`, or `.log_with_msg()` and converted into zero-sized `LoggedError` / `LoggedResult<T>`.
81+ - In debug builds, `#[track_caller]` logs the file and line number of error sites automatically. Use `.silent()` to silence expected failures.
82+
83+3. **Libc System Call Conversions (`LibcReturn`):**
84+ - When calling raw libc or C system APIs in Rust or `xwrap.rs`, use `LibcReturn::into_os_result` or `check_err` to automatically map negative integer returns or null pointers into `OsResult` or `LoggedResult`.
85+
86+4. **Zero Allocation & Binary Size Rules:**
87+ - Prefer custom `argh` derivation (`base/argh.rs`) for command-line parsing instead of adding standard argument dependencies.
88+ - Avoid `serde` overhead; use procedural `Encodable`/`Decodable` binary traits over UNIX domain sockets for IPC.
89+
90+5. **Nightly Synchronization & IPC:**
91+ - Magisk uses nightly features (`unix_socket_ancillary_data`, `nonpoison_mutex`).
92+ - Use non-poisoning mutexes/condvars for daemon threading and `send_fd`/`recv_fd` for raw file descriptor passing.
3393
