-
Notifications
You must be signed in to change notification settings - Fork 21
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation for contributing to KomaMRI using VSCode #382
base: master
Are you sure you want to change the base?
Changes from all commits
6d1bf42
d406a2e
4bf706b
bd58ea7
0e08b7c
5cb222d
b855e76
9995fa5
750bab3
6f4cc82
a98d657
6606041
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -0,0 +1,145 @@ | ||||||
# Advanced Users | ||||||
|
||||||
If you really want to stay in tune with the most recent features, test some ideas, or even contribute to the KomaMRI project, it is necessary to install and configure some tools on your machine: | ||||||
- **Juliaup:** This is the manager for installing different versions of Julia. | ||||||
- **Julia:** This is the programming language. It is advisable to install it with Juliaup. | ||||||
- **Git:** This is a version control system handy for coding. | ||||||
- **GitHub:** This is a cloud-based Git repository handy for managing the KomaMRI project. You need to create an account. | ||||||
- **VScode:** This is a code editor with support for development operations. | ||||||
- **VScode Plugins:** They enable VSCode to have more handy features. We recommend you install the following: "Julia", "Git Graph", "GitHub Pull Requests"." | ||||||
|
||||||
## Setup your Fork of KomaMRI | ||||||
|
||||||
Once everything is installed, you need to create a fork of the KomaMRI repository in your GitHub account. Go to the official [KomaMRI repository](https://github.com/JuliaHealth/KomaMRI.jl) and follow the steps below:" | ||||||
|
||||||
![](../assets/dev-fork.png) | ||||||
![](../assets/dev-fork-create.png) | ||||||
|
||||||
Now, your fork of KomaMRI should look similar to the image below: | ||||||
|
||||||
![](../assets/dev-fork-github.png) | ||||||
|
||||||
## Setup your Local Git Project | ||||||
|
||||||
Now, you need to clone your fork of the KomaMRI repository. In Julia, you can do this by opening a Julia REPL, open the package manager with the `]` button and typing the following command (make sure to replace `<github-username>` with your GitHub username):" | ||||||
```julia-repl | ||||||
(@v1.10) pkg> dev https://github.com/<github-username>/KomaMRI.jl | ||||||
``` | ||||||
|
||||||
This saves the local Git project at the `~/.julia/dev/KomaMRI/` directory. You can then open VSCode and navigate to this folder; it should look like this: | ||||||
|
||||||
![](../assets/dev-vscode-git-project.png) | ||||||
|
||||||
## Setup the Julia Environment | ||||||
|
||||||
To run KomaMRI locally, you need to set up the Julia environment for this project. The environment's information is ultimately defined by the `Manifest.toml` file. However, since you don't have that file yet, you'll need to create it using the information from the `Project.toml` file. | ||||||
|
||||||
Let's select the environment for your KomaMRI project: | ||||||
|
||||||
![](../assets/dev-vscode-select-komamri-environment.png) | ||||||
|
||||||
Now, open a Julia REPL: | ||||||
|
||||||
![](../assets/dev-open-julia-repl.png) | ||||||
|
||||||
In the Julia REPL, you have to create the `Manifest.toml` file with the `develop` command, considering the local folders `KomaMRIBase`, `KomaMRICore`, `KomaMRIFiles`, and `KomaMRIPlots`. Additionally, you can install all the dependencies listed in the `Manifest.toml` with the `instantiate` command: | ||||||
```julia-repl | ||||||
(KomaMRI) pkg> dev ./KomaMRIBase ./KomaMRICore ./KomaMRIFiles ./KomaMRIPlots | ||||||
|
||||||
(KomaMRI) pkg> instantiate | ||||||
``` | ||||||
|
||||||
With these steps, your environment has been configured. | ||||||
|
||||||
## Run KomaMRI Locally | ||||||
|
||||||
You can now run the KomaMRI's user interface: | ||||||
```julia-repl | ||||||
julia> using KomaMRI | ||||||
|
||||||
julia> KomaUI() | ||||||
``` | ||||||
![](../assets/dev-launch-ui.png) | ||||||
|
||||||
Let's see what the default phantom is in the user interface by clicking on the `Phantom dropdown` and then pressing the `View Phantom` button: | ||||||
|
||||||
![](../assets/dev-default-phantom-brain.png) | ||||||
|
||||||
You can close the KomaMRI's user interface. | ||||||
|
||||||
## Make Changes and Upload Them | ||||||
|
||||||
So far so good. However, if you want to make some changes to your GitHub Fork or even contribute to the KomaMRI project, you'll need to make some changes to the local Git repository. In the following example, we will change the default phantom displayed in the user interface. | ||||||
|
||||||
First, create a branch with a descriptive name. For example, you can use `patch-ui-default-phantom` as the branch name: | ||||||
|
||||||
![](../assets/dev-branch.png) | ||||||
![](../assets/dev-branch-name.png) | ||||||
|
||||||
In this new branch, we are going to edit the `setup_phantom` function located in the file `src/ui/ExportUIFunctions.jl`. Specifically, we will replace the line where a brain phantom is defined with the function `pelvis_brain2D`: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I believe this should be
Suggested change
|
||||||
|
||||||
![](../assets/dev-branch-edit.png) | ||||||
|
||||||
Next, compile the function `setup_phantom`. Simply place the cursor inside the `setup_phantom` function and press `Alt + Enter`: | ||||||
|
||||||
![](../assets/dev-branch-compile.png) | ||||||
|
||||||
Now, let's see the new default phantom in the user interface by clicking on the `Phantom dropdown` and then pressing the `View Phantom` button: | ||||||
|
||||||
```julia-repl | ||||||
julia> KomaUI() | ||||||
``` | ||||||
|
||||||
![](../assets/dev-default-phantom-pelvis.png) | ||||||
|
||||||
Everything looks good; we effectively changed the default phantom. Let's stage the changes: | ||||||
|
||||||
![](../assets/dev-stage-changes.png) | ||||||
|
||||||
And commit the changes with a descriptive name: | ||||||
|
||||||
![](../assets/dev-commit-changes.png) | ||||||
|
||||||
Let's upload these changes to your GitHub fork or to the official KomaMRI repository by selecting the `origin` or the `upstream` option, respectively: | ||||||
|
||||||
![](../assets/dev-publish.png) | ||||||
|
||||||
![](../assets/dev-pullreq.png) | ||||||
|
||||||
![](../assets/dev-pullreq-name.png) | ||||||
|
||||||
Well done! You have uploaded your changes in a branch to a remote repository. | ||||||
|
||||||
|
||||||
Comment on lines
+112
to
+113
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Forking KomaIf you try to commit or generate a pull request at this point, you will get an To use you fork in VSCode click "master" in the status bar: and select your remote branch |
||||||
## About Julia Environments and Subdirectories | ||||||
|
||||||
So far, the `KomaMRI` package has 4 subdirectories: `KomaMRIBase`, `KomaMRICore`, `KomaMRIPlots`, and `KomaMRIFiles`. These subdirectories are proper Julia packages by themselves, so each has its own `Project.toml` file, which needs to resolve an environment defined ultimately by a `Manifest.toml`. | ||||||
|
||||||
This is how these packages are related: | ||||||
- `KomaMRIBase` doesn't depend on any of these other subdirectories. | ||||||
- `KomaMRICore` depends directly on `KomaMRIBase`. | ||||||
- `KomaMRIPlots` depends directly on `KomaMRIBase`. | ||||||
- `KomaMRIFiles` depends directly on `KomaMRIBase`. | ||||||
- `KomaMRI` depends directly on `KomaMRICore`, `KomaMRIPlots`, and `KomaMRIFiles`." | ||||||
|
||||||
If you want to edit only the direct contents of one of these packages, you simply need to activate the Julia package and then instantiate it to generate the `Manifest.toml` file and install dependencies. However, if you want to make changes that involve the packages and their direct dependencies, you need to create an environment that reflects those dependencies. | ||||||
|
||||||
For instance, to edit `KomaMRICore` and its direct dependency `KomaMRIBase` you need to create the `Manifest.toml` like so: | ||||||
```julia-repl | ||||||
user@machine ~/.julia/dev/KomaMRI | ||||||
$ julia | ||||||
|
||||||
(@v1.10) pkg> activate KomaMRICore | ||||||
|
||||||
(KomaMRICore) pkg> dev ./KomaMRIBase | ||||||
``` | ||||||
|
||||||
And for creating the `Manifest.toml` file for `KomaMRI`, which considers all the subdirectories, you have to do the following: | ||||||
```julia-repl | ||||||
user@machine ~/.julia/dev/KomaMRI | ||||||
$ julia | ||||||
|
||||||
(@v1.10) pkg> activate . | ||||||
|
||||||
(KomaMRI) pkg> dev ./KomaMRIBase ./KomaMRICore ./KomaMRIFiles ./KomaMRIPlots | ||||||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I actually encountered an error when I ran this:
However, I was able to follow the rest of the instructions just fine, since all that is needed at this stage is to get the source code checked out in to the Julia dev directory. Maybe the same could be achieved without error using a
git checkout
, or a comment could be added to let the reader know that this error can be safely ignored.Secondly, should the text remind inexperienced users to check they have set up their anonymous GitHub email address for the local repository? Otherwise push may fail later if they opted to keep their email address private in their GitHub settings.