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 repo on github.
  2. Create the package locally. If using PkgTemplates.jl, this automatically sets the github repo as the remote.
  3. Write some code.
  4. Using the Github client: add the local repo.
  5. 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, PackageCompatUI is useful. The compat_ui() command 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.

Package missing from cache:

  • Remove precompile caches: rm -rf ~/.julia/compiled

Private Registries

In principle, it is easy to create your own registry (see discourse for a guide). The key to making it practical is LocalRegistry.jl.

Once the registry is created and uploaded to github, "enable" it with registry add URL where URL is of the form https://github.com/hendri54/registryLH.

Any registry that lives in ~/.julia/registries is automatically used by Pkg.