Skip to content

Packages

Why Packages?

The alternative to creating a package is to create an environment with a bunch of jl files that contain a module.

Reasons why packages are better:

  1. Revise.jl has an easier time tracking code changes.
  2. Pkg.test works.
  3. Code is easier to reuse with just a simple Pkg.add and Pkg.develop and using MyPkg. No need for includet statements.
  4. If the module is used in multiple modules in the same environment, one has to make sure that each module uses the same version of MyPkg. One has to avoid multiple includet("MyPkg.jl") which would create multiple instances of MyPkg.

Creating packages

  1. Create the package locally. If using PkgTemplates.jl, this automatically initializes the github repo and sets it as the origin (git remote add origin <url>).
  2. Write some code.
  3. Push to github.

PkgTemplates.jl

The typical flow would be:

using PkgTemplates
gitIgnore = ["*.jl.cov", "*.jl.*.cov", "*.jl.mem", "/deps/deps.jl", "/docs/build"];
t = Template(;
    dir = joinpath(homedir(), "Documents", "julia"),
    plugins = [
        Documenter{GitHubActions},
        Git(; jl = false, ignore = gitIgnore),
        !CompatHelper,
        !AppVeyor,
        !TravisCI,
        !TagBot
        ]);

t("MyPkg");

Note that dir points to the parent directory of the new packages to be created.

Even if one does not want to deploy documentation, the Documenter plugin is needed to create the barebones file structure.

PkgSkeleton.jl (1.5)

The easiest way for creating a package is PkgSkeleton.jl. You need to set your github info (user.name etc) using

git config --global user.name YourName

This must be done inside a git directory. Then generate generates the directory structure and the required files (Project.toml etc). Example:

PkgSkeleton.generate("dir1/MyPackage")

Details:

  • I first create the repo on github and clone it to the local dir.
  • Then I use, from the parent dir: PkgSkeleton.generate("MyPackage", skip_existing_dir = false)
  • This way everything is linked to github from the start.

Github and packages

The basic steps (after creating the package locally):

  1. Create the package on github.
  2. git branch -M main
  3. git push -u origin main

Or import the package repo into Github Desktop.

Compatibility

Enabling CompatHelper workflows is very helpful. Simply update CompatHelper.yml in the repo's .github/workflows directory and enable local actions in the github repo settings. The rest is automatic.

CompatHelper creates one PR each time a dependency experiences a breaking version bump. Rather than merging these on github, it is easier to manually edit Project.toml locally, test, commit, and then close the PRs.

For updating compat entries, PkgCompatUI is useful. It shows available versions for all packages and indicates which ones have breaking updates.

Pkg Errors

Occasionally, Pkg complains that a package is not registered. ]registry up tends to solve that issue. If that fails, one can alway remove the registry with ]registry remove General. It will be automatically installed again the next time it's needed.