Merge pull request #1 from Oichkatzelesfrettschen/codex/explain-codebase-structure-to-newcomer

Add script to sync NetBSD sources

docs/NETBSD_UPDATE.md

@@ -0,0 +1,65 @@
+# Importing newer NetBSD sources
+
+This repository contains MINIX 3 code alongside sources periodically imported
+from NetBSD. The project does not provide an automated tool for updating all
+NetBSD components at once. The general approach below may be used to bring in
+a more recent snapshot of NetBSD.
+
+1. Add the official NetBSD repository as a remote and fetch its history:
+
+    ```sh
+    git remote add netbsd https://github.com/NetBSD/src.git
+    git fetch netbsd
+    ```
+
+2. Choose the NetBSD branch or tag you want to integrate, for example
+   `netbsd-10` or a specific release tag, and check it out:
+
+    ```sh
+    git checkout -b netbsd-update netbsd/netbsd-10    # example branch
+    ```
+
+3. Merge the selected NetBSD revision into the MINIX tree. Expect many
+   conflicts that require manual resolution. Use `--allow-unrelated-histories`
+   because the two projects started from different repositories.
+
+    ```sh
+    git merge --allow-unrelated-histories netbsd/netbsd-10
+    ```
+
+4. After resolving conflicts, rebuild the entire system to verify that the
+   merge did not introduce build errors:
+
+    ```sh
+    ./build.sh -j$(nproc) tools build
+    ```
+
+   Consult `docs/UPDATING` for additional steps that may be required after
+   bringing in new code.
+
+Alternatively, set the `NETBSD_BRANCH` environment variable and run
+`releasetools/sync_netbsd.sh` to automate these steps:
+
+```sh
+NETBSD_BRANCH=netbsd-10 releasetools/sync_netbsd.sh
+```
+
+
+Updating to a new NetBSD snapshot touches a large number of files and may
+change interfaces used throughout MINIX. Take care to review each conflict
+and test the result thoroughly before deploying.
+
+## Files affected by NetBSD updates
+
+Most directories in this tree originate from NetBSD and will change when
+syncing to a new snapshot. The following areas are commonly affected:
+
+- `sys/` – kernel sources and platform code
+- `lib/`, `libexec/` – system libraries and helper daemons
+- `bin/`, `sbin/`, `usr.bin/`, `usr.sbin/` – userland utilities
+- `include/`, `crypto/`, `external/` – headers and third-party packages
+- `tests/`, `tools/`, `distrib/` – test suite, build tools and release scripts
+
+Only the `minix/` subtree and a few `minix` programs under `usr.*` are
+maintained separately. Interface changes in any imported directory may require
+corresponding updates throughout the MINIX-specific code.

releasetools/sync_netbsd.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+# Sync NetBSD sources from upstream
+#
+# Environment variables:
+#   NETBSD_BRANCH - branch or tag to sync (required)
+#   NETBSD_REMOTE - name of git remote (default: netbsd)
+#   NETBSD_URL    - remote URL (default: https://github.com/NetBSD/src.git)
+#
+: ${NETBSD_REMOTE:=netbsd}
+: ${NETBSD_URL:=https://github.com/NetBSD/src.git}
+
+if [ -z "$NETBSD_BRANCH" ]; then
+    echo "Please set NETBSD_BRANCH to the upstream branch or tag." >&2
+    exit 1
+fi
+
+if [ ! -f build.sh ]; then
+    echo "Run this script from the repository root." >&2
+    exit 1
+fi
+
+set -e
+
+# Add remote if missing
+if ! git remote | grep -q "^${NETBSD_REMOTE}$"; then
+    git remote add "$NETBSD_REMOTE" "$NETBSD_URL"
+fi
+
+# Fetch updates from upstream
+git fetch "$NETBSD_REMOTE"
+
+UPDATE_BRANCH="netbsd-sync-${NETBSD_BRANCH}"
+
+git branch -f "$UPDATE_BRANCH" "$NETBSD_REMOTE/$NETBSD_BRANCH"
+
+find . -type f | cut -c 3- | grep -v '^\.git' | grep -v '^./minix' | sort -u > files.all
+git grep -l -i minix | grep -v '^\.git' | grep -v '^./minix' | sort -u > files.minix
+comm -23 files.all files.minix > files.netbsd
+
+while read -r file; do
+    git checkout "$UPDATE_BRANCH" -- "$file"
+done < files.netbsd
+
+rm files.all files.minix files.netbsd
+
+echo "NetBSD files synced from $NETBSD_BRANCH"