Julia Packages and GitHub actions

(I basically followed this advice to prepare these slides)

Julia basics

Download and install Julia, VSCode, and the Julia extension for VSCode
Julia REPL and its 4 different modes: normal, ], ?, ;

Adding packages:

] add Plots # Adds the Plots package to your environment

Simple example:

using Plots # Loads the Plots package
x = 0:0.1:10 # A range from 0 to 10, in steps of 0.1
y = sin.(x) # The dot applies the function to each element in x
plot(x,y) # Creates a simple plot of (x,y)
typeof(y) # Useful to inspect the type of an object

Modules: basically, namespaces for your functions, types, constants ```julia module MyModule

export ω_c # Exports “myfun” when “using MyModule”; yes, you can use unicode

function ω_c(m,q,B) # A simple function declaration q*B/m # The last computation is the return value of the function end

end

- In the REPL:
```julia
include("file_containing_the_code_above.jl") # Inputs its contents in the REPL
using .MyModule # The dot is because MyModule is defined in Main
 
ω_c(1.2,3.5,4.6) # --> 13.416666666666666

Tests: In the REPL do ] add Test and then:
```
using Test
@test ω_c(1,1,1) == 1
```
Tests can be placed in a separate file and run automatically—more on this later

Packages: go to GitHub and create an (open) repository named “MyModule.jl”
Clone it from VSCode
In the REPL do ] generate MyModule. Move the generated files to your repo and cd there
- The Project.toml file is key: it tells julia this is a Package. And it contains important information about the package and its dependencies
Do ] activate . in that folder. This will make this project the active environment: any packages we add, will be declared as dependencies
Do ] add Unitful, a package to work with SI units (although we won’t use it today)
Move your MyModule file to the src subdirectory

Example Project.toml ```toml name = “MyModule” uuid = “0ee7eb5d-809b-41c1-ada9-2f03847bf980” authors = [“Mario Merino mario.merino@uc3m.es”] version = “0.1.0”

[deps] Unitful = “1986cc42-f94f-5a68-af5c-568840ba703d”

[compat] julia = “1.3.0”

- The compat block is added manually; needed if we ever want to register the package in the julia servers for others to use

---

- Adding tests: Create a subdirectory named "test" and `cd` there. `activate` the test directory and do `] add Test`. This is a separate (sub)environment 
- Create the file `runtests.jl` in the test directory:
```julia
using Test, MyModule 
 
@test ω_c(1,1,1) == 1   

You can run the tests as if they were typed in the REPL with
```
include("tests/runtests.jl")
```
Or, you can run runtests.jl as any other julia program from the command line, just do (bash)$ julia runtests.jl

Installing the package in your Julia system:
Commit + push to GitHub. Delete the local directory to avoid confusion with the following
You can now install your package like any other, with
```
] add https://github.com/YOURUSER/MyModule.jl
```
You can now use/import the package in your applications: using MyModule
You can run all the tests of your Package with ] test MyModule
To continue developing, you can ask Julia to develop it:
```
] dev MyModule
```
This will clone the repo in ~/.julia/dev. Open this folder with VSCode and continue editing, adding functionality, committing & pushing

Documenting: Open your MyModule.jl file and add a docstring to your function: ```julia module MyModule

export ω_c # Exports “myfun” when “using MyModule”; yes, you can use unicode

””” ω_c(m,q,B)

Compute the gyrofrequency of a charged species “”” function ω_c(m,q,B) # A simple function declaration q*B/m # The last computation is the return value of the function end

end

- They are used in the help mode: `?ω_c`
- Docstrings are also used by the Documenter package

---

- Create a subdirectory named "docs"
- Generate the skeleton of the documentation (the "docs" folder is itself another Julia (sub)package):
```julia
]  activate # Without arguments, this makes the "base" environment active
]  add Documenter, DocumenterTools
 
using DocumenterTools
cd("~/.julia/dev/MyModule")
DocumenterTools.generate()

This will create a src folder inside “docs” and some files
Edit your docs/make.jl and docs/src/index.md files according to the templates provided
Run the make.jl file to build a static version of your docs

Final notes:

The Revise package is recommended when developing
To learn more about Julia, read the Julia docs
Check out the julia packages at JuliaPackages
Read the Test package documentation
To learn how the Documenter package works, read its own manual

GitHub Actions

Actions allow automatizing repetitive tasks: running all the tests of your code on each push; run them in different machines (ubuntu, windows, mac…); generate automatic documentation; publish something to a website, etc.
In this tutorial: just a basic example using the repository from before
.github directory: special files for issue templates and Actions live here

Some quick tricks:

Press “.” in any repo to edit it online with VSCode browser version
Still a preview feature: press CTRL+K to open the anything menu

Create a .github/ci.yml file following the template provided
Discuss the template
Commit, push
Edit GitHub settings to serve the GitHub Pages from the gh-pages branch
Create a release with the v0.1.0 tag

Adding badges to the README.md of the repository: ```

```

To see a more developed example, go to the PlasmaProperties repository in the EP2 GitHub organization.
Show how this repository works