Julia Packages and GitHub actions

Session checklist

(I basically followed this advice to prepare these slides)

                Equipo de Propulsión Espacial y Plasmas, Mario Merino, 2021

Julia basics

] 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
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:
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
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:
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:
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):
]  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:
[![](https://img.shields.io/badge/docs-stable-blue.svg)](https:///YOURNAME.github.io/MyModule.jl/stable)

[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://YOURNAME.github.io/MyModule.jl/dev)

[![](https://github.com/YOURNAME/MyModule.jl/workflows/CI/badge.svg)](https://github.com/YOURNAME/MyModule.jl/actions)
  • To see a more developed example, go to the PlasmaProperties repository in the EP2 GitHub organization.
  • Show how this repository works