From 9724c0374be4f9b6a384daed7650b10918806819 Mon Sep 17 00:00:00 2001 From: "Thomas A." Date: Tue, 14 Apr 2026 19:07:44 -0700 Subject: [PATCH 1/3] Reorganize SUMMARY.md --- src/SUMMARY.md | 21 ++++++++++++------- src/contributing/advance_tasks/README.md | 3 +++ .../{ => advance_tasks}/debugging.md | 0 .../updating-sources/README.md | 0 .../updating-sources}/generating-syscalls.md | 0 src/contributing/beginner_tasks/README.md | 3 +++ .../{ => beginner_tasks}/generating-stubs.md | 0 src/contributing/setting_build_environment.md | 3 +++ src/contributing/submitting_your_changes.md | 3 +++ src/guidelines.md | 3 +++ src/misc/README.md | 1 + .../google-summer-of-code.md | 0 .../high-priority-stuff.md | 0 src/{contributing => }/packaging.md | 0 14 files changed, 29 insertions(+), 8 deletions(-) create mode 100644 src/contributing/advance_tasks/README.md rename src/contributing/{ => advance_tasks}/debugging.md (100%) rename src/contributing/{ => advance_tasks}/updating-sources/README.md (100%) rename src/contributing/{ => advance_tasks/updating-sources}/generating-syscalls.md (100%) create mode 100644 src/contributing/beginner_tasks/README.md rename src/contributing/{ => beginner_tasks}/generating-stubs.md (100%) create mode 100644 src/contributing/setting_build_environment.md create mode 100644 src/contributing/submitting_your_changes.md create mode 100644 src/guidelines.md create mode 100644 src/misc/README.md rename src/{contributing => misc}/google-summer-of-code.md (100%) rename src/{contributing => misc}/high-priority-stuff.md (100%) rename src/{contributing => }/packaging.md (100%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index f435b76..6335b9c 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -36,11 +36,16 @@ - [Event Loop](internals/darlingserver/event-loop.md) - [Additional Resources](internals/additional-resources.md) - [Contributing](contributing/README.md) - - [Debugging](contributing/debugging.md) - - [Generating stubs](contributing/generating-stubs.md) - - [Generating syscalls](contributing/generating-syscalls.md) - - [High priority stuff](contributing/high-priority-stuff.md) - - [Google Summer of Code](contributing/google-summer-of-code.md) - - [Packaging](contributing/packaging.md) - - [Updating sources](contributing/updating-sources/README.md) - + - [Setting Build Environment](contributing/setting_build_environment.md) + - [Beginner Tasks](contributing/beginner_tasks/README.md) + - [Generating stubs](contributing/beginner_tasks/generating-stubs.md) + - [Advance Tasks](contributing/advance_tasks/README.md) + - [Debugging](contributing/advance_tasks/debugging.md) + - [Updating sources](contributing/advance_tasks/updating-sources/README.md) + - [Generating syscalls](contributing/advance_tasks/updating-sources/generating-syscalls.md) + - [Submitting Your Changes](contributing/submitting_your_changes.md) +- [Guidelines](guidelines.md) +- [Packaging](packaging.md) +- [Misc](misc/README.md) + - [High priority stuff](misc/high-priority-stuff.md) + - [Google Summer of Code](misc/google-summer-of-code.md) diff --git a/src/contributing/advance_tasks/README.md b/src/contributing/advance_tasks/README.md new file mode 100644 index 0000000..bcaf928 --- /dev/null +++ b/src/contributing/advance_tasks/README.md @@ -0,0 +1,3 @@ +# Advance Tasks + +*TODO* diff --git a/src/contributing/debugging.md b/src/contributing/advance_tasks/debugging.md similarity index 100% rename from src/contributing/debugging.md rename to src/contributing/advance_tasks/debugging.md diff --git a/src/contributing/updating-sources/README.md b/src/contributing/advance_tasks/updating-sources/README.md similarity index 100% rename from src/contributing/updating-sources/README.md rename to src/contributing/advance_tasks/updating-sources/README.md diff --git a/src/contributing/generating-syscalls.md b/src/contributing/advance_tasks/updating-sources/generating-syscalls.md similarity index 100% rename from src/contributing/generating-syscalls.md rename to src/contributing/advance_tasks/updating-sources/generating-syscalls.md diff --git a/src/contributing/beginner_tasks/README.md b/src/contributing/beginner_tasks/README.md new file mode 100644 index 0000000..68c766f --- /dev/null +++ b/src/contributing/beginner_tasks/README.md @@ -0,0 +1,3 @@ +# Beginner Tasks + +*TODO* diff --git a/src/contributing/generating-stubs.md b/src/contributing/beginner_tasks/generating-stubs.md similarity index 100% rename from src/contributing/generating-stubs.md rename to src/contributing/beginner_tasks/generating-stubs.md diff --git a/src/contributing/setting_build_environment.md b/src/contributing/setting_build_environment.md new file mode 100644 index 0000000..c9455fc --- /dev/null +++ b/src/contributing/setting_build_environment.md @@ -0,0 +1,3 @@ +# Building + +*TODO* diff --git a/src/contributing/submitting_your_changes.md b/src/contributing/submitting_your_changes.md new file mode 100644 index 0000000..e49f587 --- /dev/null +++ b/src/contributing/submitting_your_changes.md @@ -0,0 +1,3 @@ +# Submitting Your Changes + +*TODO* diff --git a/src/guidelines.md b/src/guidelines.md new file mode 100644 index 0000000..0b1907b --- /dev/null +++ b/src/guidelines.md @@ -0,0 +1,3 @@ +# Guidelines + +*TODO* diff --git a/src/misc/README.md b/src/misc/README.md new file mode 100644 index 0000000..2a9d4ae --- /dev/null +++ b/src/misc/README.md @@ -0,0 +1 @@ +# Misc \ No newline at end of file diff --git a/src/contributing/google-summer-of-code.md b/src/misc/google-summer-of-code.md similarity index 100% rename from src/contributing/google-summer-of-code.md rename to src/misc/google-summer-of-code.md diff --git a/src/contributing/high-priority-stuff.md b/src/misc/high-priority-stuff.md similarity index 100% rename from src/contributing/high-priority-stuff.md rename to src/misc/high-priority-stuff.md diff --git a/src/contributing/packaging.md b/src/packaging.md similarity index 100% rename from src/contributing/packaging.md rename to src/packaging.md From b592e449db8e09553378e2be1353b99cd6eaca9a Mon Sep 17 00:00:00 2001 From: "Thomas A." Date: Sun, 22 Mar 2026 17:22:25 -0700 Subject: [PATCH 2/3] Rework Contributing Page --- src/contributing/README.md | 83 +++++++++++++++++++++++++++----------- 1 file changed, 59 insertions(+), 24 deletions(-) diff --git a/src/contributing/README.md b/src/contributing/README.md index dccc7f0..063ecd6 100644 --- a/src/contributing/README.md +++ b/src/contributing/README.md @@ -1,45 +1,80 @@ # Contributing -If you are familiar with how GitHub Pull Requests work, you should feel right at home contributing to Darling. +## Setting up your development environment -## Fork the repository +[See instruction page for guidance on how to set up and build Darling.](../build-instructions.md) + +We recommend adding the following additional flags when configuring the project with cmake: + +```bash +cmake .. -DCMAKE_BUILD_TYPE=Debug -DCOMPONENTS=all +``` + +## Creating your fork + +Unless you are one of the core Darling developers who has write access to the Darling repos, you will need to create a fork to push your changes to. [If you are unsure about how to fork a repository on GitHub, please refer to the following instructions for guidance.](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository) + +If the changes you want to make live in a submodule (usually located in `src/external`. [See `.gitmodules` file for a list of all of the submodules Darling uses](https://github.com/darlinghq/darling/blob/master/.gitmodules)), you’ll need to `cd` into the submodule’s directory and use git remote to get the URL -Locate the repository that you made changes in on GitHub. The following command can help. - ```bash -cd darling/src/external/less +cd src/external/xnu/ git remote get-url origin -https://github.com/darlinghq/darling-less.git ``` -If it is an `https` scheme then you can paste the URL directly into your browser. +``` +https://github.com/darlinghq/darling-xnu.git +``` + +Normally, you are expected to create a clone of your fork and commit your changes on that cloned fork. For Darling, we recommend working off the official repo clone you created earlier and add your fork as an additional remote. + +# Adding your fork as an additional remote + +By default, a fresh clone of Darling will have the following remote: + +```bash +git remote -v +``` +``` +origin https://github.com/darlinghq/darling.git (fetch) +origin https://github.com/darlinghq/darling.git (push) +``` -Once at the page for the repository you made changes to, click the *Fork* -button. GitHub will then take you to the page for your fork of that repository. -The last step here is to copy the URL for your fork. Use the Clone or download -button to copy it. +Use `git remote add` to add your forked repo, like so: -# Commit and push your changes +```bash +git remote add https://github.com//darling.git +``` -Create and check out a branch describing your changes. In this example, we will -use `reinvent-wheel`. Next, add your fork as a remote. +If you are working off of a submodule, make sure to `cd` into the submodule’s directory first and use the forked submodule URL: ```bash -git remote add my-fork git@github.com:user/darling-less.git +cd src/external/xnu/ +git remote add https://github.com//darling-xnu.git ``` -After this, push your commits to your fork. +If you did it correctly, you should see the following: + +```bash +git remote -v +``` +``` + https://github.com//darling.git (fetch) + https://github.com//darling.git (push) +origin https://github.com/darlinghq/darling.git (fetch) +origin https://github.com/darlinghq/darling.git (push) +``` + +## Pushing your changes to your fork + +After you have created a branch and committed your changes, you can push your commits to your fork by using the following command. ```bash -git push -u my-fork reinvent-wheel +git push -u ``` -The `-u my-fork` part is only necessary when a branch has never been pushed to your fork before. +The `-u ` part is only necessary when a branch has never been pushed to your fork before. -# Submit a pull request +## Submit a pull request -On the GitHub page of your fork, select the branch you just pushed from the -branch dropdown menu (you may need to reload). Click the *New pull request* -button. Give it a useful title and descriptive comment. After this, you can -click create. +On the GitHub page of your fork, select the branch you just pushed from the branch dropdown menu (you may need to reload). Click the *New pull request* button. Give it a useful title and descriptive comment. After this, you can click create. -After this, your changes will be reviewed by a Darling Project member. +After this, your changes will be reviewed by a Darling project member. \ No newline at end of file From 3fb53f3eac095e53a8cc013c1962b592ba77de49 Mon Sep 17 00:00:00 2001 From: "Thomas A." Date: Thu, 26 Mar 2026 19:21:54 -0700 Subject: [PATCH 3/3] Add A Overview Section For the Structure of the Darling Project --- src/contributing/README.md | 47 +++++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/src/contributing/README.md b/src/contributing/README.md index 063ecd6..4a1da5f 100644 --- a/src/contributing/README.md +++ b/src/contributing/README.md @@ -1,8 +1,53 @@ # Contributing +## Understanding the structure of the Darling project + +### Submodules + +The Darling project relies heavily on the usage of submodules. The best way to understand a submodule is to think of it as repo inside of another repo. + +The [`.gitmodules` file](https://github.com/darlinghq/darling/blob/master/.gitmodules) provides a list of submodules that the `darling` repo uses. + +For example, let's take a look at the `darling-xnu` repo that the `darling` repo includes. + +``` +[submodule "src/external/xnu"] +path = src/external/xnu +url = ../darling-xnu.git +``` + +The path indicates the location of the submodule, while the url is the link to the git repo. + +> [!NOTE] +> A git submodule's URL path would usually be absolute instead of relative. +> ``` +> [submodule "src/external/xnu"] +> path = src/external/xnu +> url = https://github.com/darlinghq/darling-xnu.git +> ``` +> However, the Darling team has made the deliberate decision to use a relative path instead, mainly for the following reasons: +> * To allow cloning/updating the project either through `https` or `ssh` +> * To make it easier to hard fork this project. + +When you `cd` into the `src/external/xnu` directory, you are working off of the `darling-xnu` repo, instead of the usual `darling` repo. + +```bash +cd ~/Downloads/darling +git remote -v +# origin https://github.com/darlinghq/darling.git (fetch) +# origin https://github.com/darlinghq/darling.git (push) +``` +```bash +cd ~/Downloads/darling/src/external/xnu +git remote -v +# origin https://github.com/darlinghq/darling-xnu.git (fetch) +# origin https://github.com/darlinghq/darling-xnu.git (push) +``` + +[For additional details on git submodules, we recommend reading the submodule section in the git-scm website](https://git-scm.com/book/en/v2/Git-Tools-Submodules) ## Setting up your development environment -[See instruction page for guidance on how to set up and build Darling.](../build-instructions.md) +If you have not already, [please see instruction page for guidance on how to set up and build Darling.](../build-instructions.md) We recommend adding the following additional flags when configuring the project with cmake: