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/README.md b/src/contributing/README.md index dccc7f0..4a1da5f 100644 --- a/src/contributing/README.md +++ b/src/contributing/README.md @@ -1,45 +1,125 @@ # Contributing -If you are familiar with how GitHub Pull Requests work, you should feel right at home contributing to Darling. +## Understanding the structure of the Darling project -## Fork the repository +### 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 + +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: + +```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 +``` -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. +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. -# Commit and push your changes +# Adding your fork as an additional remote -Create and check out a branch describing your changes. In this example, we will -use `reinvent-wheel`. Next, add your fork as a remote. +By default, a fresh clone of Darling will have the following remote: ```bash -git remote add my-fork git@github.com:user/darling-less.git +git remote -v +``` +``` +origin https://github.com/darlinghq/darling.git (fetch) +origin https://github.com/darlinghq/darling.git (push) ``` -After this, push your commits to your fork. +Use `git remote add` to add your forked repo, like so: + +```bash +git remote add https://github.com//darling.git +``` + +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 +cd src/external/xnu/ +git remote add https://github.com//darling-xnu.git +``` + +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 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