Skip to content

2.first-package.md

Latest commit

 

History

History
99 lines (75 loc) · 3.87 KB

2.first-package.md

File metadata and controls

99 lines (75 loc) · 3.87 KB

Packages and projects

Julia packages are scattered on Github, e.g. the package Yao is in a Github repo Yao.jl. To locate these packages, Julia uses the a special Github repository as the registry of packages. The default one is called General registry.

(@v1.8) pkg> registry status
Registry Status 
 [23338594] General (https://github.com/JuliaRegistries/General.git)

Each package has a special file called Project.toml in the top level folder, which includes the dependency information. When you install a package, Julia resolves this dependency tree and install the dependencies and generate the Manifest.toml file.

read more...

Create and release your first package

1. Create a package using PkgTemplates

It is recommended to start a new Julia project as a Julia package so that the dependency can be resolved properly. It is very simple to create a new Julia package with PkgTemplates. A minimum example is as follows.

pkg> add PkgTemplates

julia> using PkgTemplates

julia> tpl = Template(; user="MyGithubUserOrOrg", plugins=[
    GitHubActions(; extra_versions=["nightly"]),
    Git(),
    Codecov(),
    Documenter{GitHubActions}(),
])

julia> tpl("Demo")

A fresh new project will be generate in folder ~/.julia/dev/Demo (or %HOME%/.julia/dev/Demo for Windows users). The file structure of this project is

(base) ➜  Demo git:(main) tree .
.
├── docs
│   ├── make.jl                 # The make file for the documents
│   ├── Manifest.toml           # The resolved dependency for the `docs` environment
│   ├── Project.toml            # The dependency specification for the `docs` environment
│   └── src
│       └── index.md            # The document home page
├── .github
│   └── workflows               # Files in this folder specify jobs run by Github Action automatically.
│       ├── CI.yml              # Run tests and calculate the test coverage
│       ├── CompatHelper.yml    # Help your package dependency up to date by creating a pull request.
│       └── TagBot.yml          # Auto-tag a version after registering a new version in a Julia registry.
├── .gitignore      # Ignored files will not be considered a part of the `git` repo.
├── LICENSE         # MIT license by default
├── Manifest.toml   # The resolved dependency
├── Project.toml    # The package name, UUID and dependencies
├── README.md       # README in markdown format
├── src             # The folder for Julia source code
│   └── Demo.jl     # The main file for the `Demo` module
└── test            # The folder for Julia test code
    └── runtests.jl # The main file for testing.

References

Some extra steps are required,

  • Setup the Github pages,
  • Connect your repo with CodeCov correctly.

2. Create a Github repo

The github repo name should be the same as your Julia package name. In our example, it is Demo.jl. Push your local files to the remote.

3. Develop and manage your package dependency

4. Release your package

You can offically release this package to make it accessible to the public by registering your package in Julia's General registry. You may find an instruction about how to register a package in the github repo Registrator.jl. After a 3 days review procedure, your package will be installable in the Pkg mode.

How to contribute to a package

Fork a package,

pkg> dev <link to github repo>

Explain package management. Local and global environment

Remove access.

How to create a package, specify project.toml