Home

PkgTemplates

Stable Latest Build Status Build Status Codecov

PkgTemplates is a Julia package for creating new Julia packages in an easy, repeatable, and customizable way.

Installation

pkg> add PkgTemplates

Usage

Assuming you have the relatively standard Git options user.name, user.email and github.user set up globally with git config --global, the simplest template requires no arguments:

julia> using PkgTemplates

julia> t = Template()
Template:
  → User: travis
  → Host: github.com
  → License: MIT (Travis CI User 2019)
  → Package directory: ~/.julia/dev
  → Minimum Julia version: v1.0
  → SSH remote: No
  → Commit Manifest.toml: No
  → Plugins: None

julia> generate("MyPkg", t)
Generating project MyPkg:
    /home/travis/.julia/dev/MyPkg/Project.toml
    /home/travis/.julia/dev/MyPkg/src/MyPkg.jl
[ Info: Initialized Git repo at /home/travis/.julia/dev/MyPkg
[ Info: Set remote origin to https://github.com/travis/MyPkg.jl
 Resolving package versions...
  Updating `~/.julia/dev/MyPkg/Project.toml`
  [8dfed614] + Test 
  Updating `~/.julia/dev/MyPkg/Manifest.toml`
  [2a0f44e3] + Base64 
  [8ba89e20] + Distributed 
  [b77e0a4c] + InteractiveUtils 
  [56ddb016] + Logging 
  [d6f4376e] + Markdown 
  [9a3f8284] + Random 
  [9e88b42a] + Serialization 
  [6462fe0b] + Sockets 
  [8dfed614] + Test 
  Updating registry at `~/.julia/registries/General`
  Updating git-repo `https://github.com/JuliaRegistries/General.git`
[?25l[?25h Resolving package versions...
  Updating `~/.julia/dev/MyPkg/Project.toml`
 [no changes]
  Updating `~/.julia/dev/MyPkg/Manifest.toml`
  [2a0f44e3] - Base64 
  [8ba89e20] - Distributed 
  [b77e0a4c] - InteractiveUtils 
  [56ddb016] - Logging 
  [d6f4376e] - Markdown 
  [9a3f8284] - Random 
  [9e88b42a] - Serialization 
  [6462fe0b] - Sockets 
  [8dfed614] - Test 
[ Info: activating new environment at ~/build/invenia/PkgTemplates.jl/docs/Project.toml.
[ Info: Committed 6 files/directories: src/, Project.toml, test/, README.md, LICENSE, .gitignore
 Resolving package versions...
  Updating `~/build/invenia/PkgTemplates.jl/docs/Project.toml`
  [75fc1c40] + MyPkg v0.1.0 [`~/.julia/dev/MyPkg`]
  Updating `~/build/invenia/PkgTemplates.jl/docs/Manifest.toml`
  [75fc1c40] + MyPkg v0.1.0 [`~/.julia/dev/MyPkg`]
[ Info: New package is at /home/travis/.julia/dev/MyPkg

julia> run(`git -C $(joinpath(t.dir, "MyPkg")) ls-files`);
.gitignore
LICENSE
Project.toml
README.md
src/MyPkg.jl
test/runtests.jl

However, we can also configure a number of keyword arguments to Template:

julia> using PkgTemplates

julia> t = Template(;
           user="myusername",
           license="MIT",
           authors=["Chris de Graaf", "Invenia Technical Computing Corporation"],
           dir="~/code",
           julia_version=v"0.7",
           ssh=true,
           plugins=[
               TravisCI(),
               Codecov(),
               Coveralls(),
               AppVeyor(),
               GitHubPages(),
           ],
       )
Template:
  → User: myusername
  → Host: github.com
  → License: MIT (Chris de Graaf, Invenia Technical Computing Corporation 2019)
  → Package directory: ~/code
  → Minimum Julia version: v0.7
  → SSH remote: Yes
  → Commit Manifest.toml: No
  → Plugins:
    • AppVeyor:
      → Config file: Default
      → 0 gitignore entries
    • Codecov:
      → Config file: None
      → 3 gitignore entries: "*.jl.cov", "*.jl.*.cov", "*.jl.mem"
    • Coveralls:
      → Config file: None
      → 3 gitignore entries: "*.jl.cov", "*.jl.*.cov", "*.jl.mem"
    • GitHubPages:
      → 0 asset files
      → 2 gitignore entries: "/docs/build/", "/docs/site/"
    • TravisCI:
      → Config file: Default
      → 0 gitignore entries

julia> generate("MyPkg2", t)
Generating project MyPkg2:
    /home/travis/code/MyPkg2/Project.toml
    /home/travis/code/MyPkg2/src/MyPkg2.jl
[ Info: Initialized Git repo at /home/travis/code/MyPkg2
[ Info: Set remote origin to git@github.com:myusername/MyPkg2.jl.git
[ Info: Created empty gh-pages branch
 Resolving package versions...
[ Warning: julia version requirement for project not satisfied
  Updating `~/code/MyPkg2/Project.toml`
  [8dfed614] + Test 
  Updating `~/code/MyPkg2/Manifest.toml`
  [2a0f44e3] + Base64 
  [8ba89e20] + Distributed 
  [b77e0a4c] + InteractiveUtils 
  [56ddb016] + Logging 
  [d6f4376e] + Markdown 
  [9a3f8284] + Random 
  [9e88b42a] + Serialization 
  [6462fe0b] + Sockets 
  [8dfed614] + Test 
  Updating registry at `~/.julia/registries/General`
  Updating git-repo `https://github.com/JuliaRegistries/General.git`
[?25l[?25h Resolving package versions...
[ Warning: julia version requirement for project not satisfied
  Updating `~/code/MyPkg2/Project.toml`
 [no changes]
  Updating `~/code/MyPkg2/Manifest.toml`
  [2a0f44e3] - Base64 
  [8ba89e20] - Distributed 
  [b77e0a4c] - InteractiveUtils 
  [56ddb016] - Logging 
  [d6f4376e] - Markdown 
  [9a3f8284] - Random 
  [9e88b42a] - Serialization 
  [6462fe0b] - Sockets 
  [8dfed614] - Test 
[ Info: activating new environment at ~/build/invenia/PkgTemplates.jl/docs/Project.toml.
 Resolving package versions...
 Installed JSON ─────── v0.20.0
 Installed Documenter ─ v0.22.4
  Updating `~/code/MyPkg2/docs/Project.toml`
  [e30172f5] + Documenter v0.22.4
  Updating `~/code/MyPkg2/docs/Manifest.toml`
  [ffbed154] + DocStringExtensions v0.7.0
  [e30172f5] + Documenter v0.22.4
  [682c06a0] + JSON v0.20.0
  [2a0f44e3] + Base64 
  [ade2ca70] + Dates 
  [8ba89e20] + Distributed 
  [b77e0a4c] + InteractiveUtils 
  [76f85450] + LibGit2 
  [56ddb016] + Logging 
  [d6f4376e] + Markdown 
  [a63ad114] + Mmap 
  [44cfe95a] + Pkg 
  [de0858da] + Printf 
  [3fa0cd96] + REPL 
  [9a3f8284] + Random 
  [ea8e919c] + SHA 
  [9e88b42a] + Serialization 
  [6462fe0b] + Sockets 
  [8dfed614] + Test 
  [cf7118a7] + UUIDs 
  [4ec0a83e] + Unicode 
[ Info: activating new environment at ~/build/invenia/PkgTemplates.jl/docs/Project.toml.
[ Info: Committed 9 files/directories: src/, Project.toml, test/, README.md, LICENSE, .travis.yml, docs/, .appveyor.yml, .gitignore
[ Info: Remember to push all created branches to your remote: git push --all
 Resolving package versions...
┌ Warning: julia version requirement for package MyPkg2 not satisfied
└ @ Pkg.Operations /buildworker/worker/package_linux64/build/usr/share/julia/stdlib/v1.1/Pkg/src/Operations.jl:154
  Updating `~/build/invenia/PkgTemplates.jl/docs/Project.toml`
  [786cca88] + MyPkg2 v0.1.0 [`~/code/MyPkg2`]
  Updating `~/build/invenia/PkgTemplates.jl/docs/Manifest.toml`
  [786cca88] + MyPkg2 v0.1.0 [`~/code/MyPkg2`]
[ Info: New package is at /home/travis/code/MyPkg2

julia> run(`git -C $(joinpath(t.dir, "MyPkg2")) ls-files`);
.appveyor.yml
.gitignore
.travis.yml
LICENSE
Project.toml
README.md
docs/Manifest.toml
docs/Project.toml
docs/make.jl
docs/src/index.md
src/MyPkg2.jl
test/runtests.jl

If that looks like a lot of work, you can also create templates interactively with interactive_template:

asciicast

And if that's still too much work for you, you can call interactive_template with fast=true to use default values for everything but username and plugin selection.

You can also use generate_interactive to interactively generate a template and then immediately use it to create a new package.

Comparison to PkgDev

PkgTemplates is similar in functionality to PkgDev's generate function. However, PkgTemplates offers more customizability in templates and more extensibility via plugins. For the package registration and release management features that PkgTemplates doesn't include, you are encouraged to use AttoBot instead.

Contributing

It's extremely easy to extend PkgTemplates with new plugins. To get started, check out the plugin development guide.