# 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, ], ?, ;
] 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

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
• 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