Tutorials > Julia Programming: a Hands-on Tutorial

Creating a New Project

by Martin D. Maas, Ph.D

Last updated: 2021-11-16

If you want to keep you code well organized, the first step is to create a project.

Basic Directory Structure

Let’s begin by creating a basic directory structure to store our project’s files. We will use (at least) the following folders:

Of course, this is a basic setup. Having tests and documentation is considered mandatory for good programming practices, but nothing stops you from adding additional folders.

Two common choices are:

Create the Source Tree and TOML files

Now let’s create the basic source tree, and the project’s TOML files

pkg > generate MyProject

This will create the following source tree:

├── Project.toml
└── src
    └── MyProject.jl

MyProject.jl will contain a Hello World function named greet():

module MyProject

greet() = print("Hello World!")

end # module

The Project.toml and Manifest.toml are central to a project. While Project.toml can be edited manually, the Manifest.toml file is generated and maintained by Pkg, so should never be modified manually.

Exit the Julia session, and, from a linux terminal, type

mkdir -p MyProject/{docs,tests}

to create the remainder folders you need.

Activating the Project Environment

To activate the project environment, if you open a Julia session from within the project’s folder, from the REPL type

pkg > activate .

You can also type activate MyProject if you are on the parent folder. Your prompt should change into something of the form

(MyProject) pkg >

Equivalently, from the terminal, start Julia with the following command

julia --project=.

Adding dependencies

After activating the current environment, you can also add dependencies. For example, let’s add the Plots package.

(MyProject) pkg > add Plots

Our Project.toml should now look like something

name = "MyProject"
uuid = "a5927f71-4e94-4484-9e8d-767c56d7f0c4"
authors = ["yourname <[email protected]>"]
version = "0.1.0"

Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"

Using your project

Once activated you activate the project environment, you can now call your greet function with the following code:

using MyProject

Did you modify MyProject.jl? If you are working interactively, testing things and adding them to your project’s module, you might notice that calling using MyProject again doesn’t do anything. This can be annoying.

In order to force the recompilation of your project’s files every time you call using MyProject from the REPL, you need to include the Revise.jl package to your working environment.

Simply start Julia, and install the Revise package in the global environment (that is, there is no need to install it as a project dependency), then activate the project environment and do:

using Revise
using MyProject

### Introduce modifications in the file MyProject.jl

using MyProject

Now, the second time you call the function, the changes you’ve made in MyProject.jl will be reflected properly.


Ok, we’ve got the basics covered. In subsequent posts we will go about structuring our code into modules, and cover some good programming practices like writing tests and relying on automatically-generated documentation. So stay tuned!

Ask me a question or send me your comments!

Don't hesitate to ask me any question about the topics I cover on this blog!

Click here to reach out!