Two questions on package development

General Usage
1

Hello,

I’m facing two uncomfortable issues when developing a package:

  • How to install it? Currently I install it from Github with Pkg.add(url = ......). That does not look serious.

  • Once it is installed, I have a problem for updating the documentation with Documenter.jl (makedocs(...)): the documentation is not updated because Documenter.jl takes the installed version of the package. How to deal with this issue?

2

I usually use PkgTemplates.jl to setup my package structure.

That is usually invoked as follows:

using PkgTemplates
Template(interactive=true)("MyPkg")

Within the MyPkg folder, usually (~/.juila/dev/MyPkg/), there will be a docs folder. In there, PkgTemplates.jl has setup a Julia project to build the documentation. In particular, this contains a make.jl. Here is an example from ArrayAllocators.jl:

The associated Manifest.toml will point to the paths of the particular packages I want. In this the Manifest.toml says I want to use ArrayAllocators.jl from the parent directory:

3

Thanks. I also use PkgTemplates. Can you install the package without using Github?

4

If you’re developing a package, you should be using dev/develop, not add.

2 Likes
5

Yes. Here is the documentation:

https://pkgdocs.julialang.org/v1/api/#Pkg.add

In particular, take a look at PackageSpec which has a path keyword argument.
https://pkgdocs.julialang.org/v1/api/#Pkg.PackageSpec

Let’s say I use PkgTemplates and customize dir to be ~/src so the package lives at ~/src/MyPkg as follows:

julia> using PkgTemplates

julia> Template(interactive=true)("MyPkg")
Template keywords to customize:
[press: d=done, a=all, n=none]
   [ ] user
   [ ] authors
 > [X] dir
   [ ] host
   [ ] julia
   [ ] plugins
Enter value for 'dir' (String, default="~/.julia/dev"): ~/src
[ Info: Running prehooks
[ Info: Running hooks
  Activating project at `~/src/MyPkg`
...

Then I use the Pkg REPL as follows to add the package to a temporary environment:

(@v1.7) pkg> activate --temp
  Activating new project at `/tmp/jl_OOV4GX`

(jl_OOV4GX) pkg> add ~/src/MyPkg
     Cloning git-repo `/home/mkitti/src/MyPkg`
    Updating git-repo `/home/mkitti/src/MyPkg`
   Resolving package versions...
    Updating `/tmp/jl_OOV4GX/Project.toml`
  [6b62e0e2] + MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main`
    Updating `/tmp/jl_OOV4GX/Manifest.toml`
  [6b62e0e2] + MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main`
Precompiling project...
  1 dependency successfully precompiled in 1 seconds

As Chris, mentioned, I can also dev the package:

(jl_OOV4GX) pkg> dev ~/src/MyPkg
   Resolving package versions...
    Updating `/tmp/jl_OOV4GX/Project.toml`
  [6b62e0e2] ~ MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main` ⇒ v0.1.0 `~/src/MyPkg`
    Updating `/tmp/jl_OOV4GX/Manifest.toml`
  [6b62e0e2] ~ MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main` ⇒ v0.1.0 `~/src/MyPkg`

If you prefer to use the Pkg API, this is the equivalent of the above:

julia> using Pkg

julia> Pkg.activate(temp=true)
  Activating new project at `/tmp/jl_xGkOLr`

julia> Pkg.add(path="/home/mkitti/src/MyPkg")
    Updating git-repo `/home/mkitti/src/MyPkg`
   Resolving package versions...
    Updating `/tmp/jl_xGkOLr/Project.toml`
  [6b62e0e2] + MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main`
    Updating `/tmp/jl_xGkOLr/Manifest.toml`
  [6b62e0e2] + MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main`

julia> Pkg.develop(path="/home/mkitti/src/MyPkg")
   Resolving package versions...
    Updating `/tmp/jl_xGkOLr/Project.toml`
  [6b62e0e2] ~ MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main` ⇒ v0.1.0 `~/src/MyPkg`
    Updating `/tmp/jl_xGkOLr/Manifest.toml`
  [6b62e0e2] ~ MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main` ⇒ v0.1.0 `~/src/MyPkg`

If you want to use PackageSpec directly, that is also possible:

julia> using Pkg

julia> mypkg = PackageSpec(path="/home/mkitti/src/MyPkg")
PackageSpec(
  path = /home/mkitti/src/MyPkg
  version = *
)

julia> Pkg.add(mypkg)
    Updating git-repo `/home/mkitti/src/MyPkg`
   Resolving package versions...
    Updating `/tmp/jl_atZNj8/Project.toml`
  [6b62e0e2] + MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main`
    Updating `/tmp/jl_atZNj8/Manifest.toml`
  [6b62e0e2] + MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main`

julia> Pkg.develop(mypkg)
   Resolving package versions...
    Updating `/tmp/jl_atZNj8/Project.toml`
  [6b62e0e2] ~ MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main` ⇒ v0.1.0 `~/src/MyPkg`
    Updating `/tmp/jl_atZNj8/Manifest.toml`
  [6b62e0e2] ~ MyPkg v0.1.0 `/home/mkitti/src/MyPkg#main` ⇒ v0.1.0 `~/src/MyPkg`

Just in case it is confusing, you only have to use either add or develop.

6

There is one other interface to Pkg that uses the pkg String macro:

julia> using Pkg

julia> pkg"activate --temp"
  Activating new project at `/tmp/jl_bosGj4`

julia> pkg"dev ~/src/MyPkg"
   Resolving package versions...
    Updating `/tmp/jl_bosGj4/Project.toml`
  [6b62e0e2] + MyPkg v0.1.0 `~/src/MyPkg`
    Updating `/tmp/jl_bosGj4/Manifest.toml`
  [6b62e0e2] + MyPkg v0.1.0 `~/src/MyPkg`
7

Thanks!