I have created my first Julia package! It is called ProjectRoot and is a small utility package that helps with file referencing withing a project-oriented workflow.
I’ve stolen the idea of the package from the R and Python packages here and pyprojroot, which are package that I have used frequently in the past to simplify file referencing for research projects, particularly when referencing data files or creating plot files in a project.
Installation
The package is on the general Julia registry, so it can be installed in Julia by calling
]add ProjectRoot
Usage
The package is designed to be light on dependencies and carries only a single exported macro, @projectroot
. And its usage is simple. Consider the following simple directory structure.
MyProject
├── scripts
│ └── A.jl
├── src
│ └── B.jl
└── Project.toml
If you want to refer to a file, say src/B.jl
, you simply need to use
@projectroot("src", "B.jl")
anywhere in your project, for instance in scripts/A.jl
.
How it Works
The @projectroot
macro fetches the file from where it is called and then recursively searches upwards in the file hierarchy until it finds one of the following:
- A
.projectroot
file - A
Project.toml
file - A
JuliaProject.toml
file - A
Manifest.toml
file - A
.git
folder - An
.svn
folder
The search terminates when it finds one of these files or when you reach the root of the file system. And this is what @projectroot
returns.
String interpolation is also supported, so you can use
= "B.jl"
file @projectroot("src") * "/$(file)"
and so on.
REPL
Calling @projectroot
from the REPL uses the same logic as above, but the search starts from the current working directory instead.
Alternatives
There is already similar functionality in the excellent DrWatson package. But I generally prescribe to the Unix philosophy (Doug McIlroy):
Make each program do one thing well. To do a new job, build afresh rather than complicate old programs by adding new “features”.
So if you just need a lightweight package in the same spirit as here
and pyprojroot
, then ProjectRoot
might just be the right tool for you.
Contributing
As always, I am happy for any kind of contribution. This is my first Julia package and I still haven’t wrapped my head around all the intricacies of Julia and its package ecosystem. So if you have any suggestions, please let me know. The source code is stored in the GitHub repository at jolars/ProjectRoot.jl and you can find the documentation for the latest stable version here.