Every folder with an `Project.toml` file has it's own environment (see below)
The "base" environment is active by default:
``` julia
(@v1.9) pkg>
```
Keep this as empty+tidy as possible!
Tip: (you could also start julia by `julia --project="."`)
### Typical commands
##### `activate`
Use `activate .` or `activate ./path/to` creates a new `Project.toml` in the selected folder (`.` means current folder), or activates it, if it already exists.
##### `status` (`st`)
Shows the currently installed packages
##### `add`
Multiple ways to add packages to the `Project.toml`:
Folders have to be git-repositories, see below. Probably better use `develop`
:::
##### `remove` (`rm`)
remove package from `Project.toml` (not from `~/.julia`, use `gc` - garbage collect for this)
##### `develop`
- `dev --local UnicodePlots`
- `dev ./Path/To/LocalPackage/`
::: callout-note
You can't select a branch with `dev` and need to do it manually
:::
::: callout-note
You are asking for the difference of `dev ./Path/Package` and `add ./Path/Package`? Good question! `dev` will always track the actual content of the folder - whereas `add` will make a "snapshot" of the last commit in that folder (has to be an git for `add`!). And you have to use `]up` to actually update to new changes
:::
##### `pin` / `free`
You can pin versions of packages, so that they are not updated. Unpin with `free` - also undo `develop` by using `free`
##### `instantiate` / `resolve`
`instantiate` setup all dependencies in the given `Project.toml`+`Manifest.toml`
`resolve` update the `Manifest.toml` to respect the local setup
Several thousand packages exist in Julia already. Take a thorough look before starting something new!
### Minimal requirements for `]add` to work
Minimal structure
One git-repository containing:
- `./src/MyStatsPackage.jl`
- (`module MyStatsPackage`)
- `./Project.toml`
- `name = "MyStatsPackage"`
- `uuid ="b4cd1eb8-1e24-11e8-3319-93036a3eb9f3"`
- (`[compat]` entries)
- (`version= "0.1.0"`)
### Additional requirements to register
Julia supports many registries (you can host your own!), which are just fancy GITs that index what version is available at what git-url for each registered package.
The default registry is [JuliaRegistries/General](https://github.com/JuliaRegistries/General).
[To register at the general registiry, you need additionally:](https://juliaregistries.github.io/RegistryCI.jl/stable/guidelines/):
- `[compat]` entries for all dependencies
- a `version=`
- a supported license
- Some restrictions on the name (e.g. nothing with `Julia`, only ASCII, etc.)
## Let's generate our first package!
```julia
] generate MyStatsPackage
```
### Adding dependencies
```julia
]activate ./path/to/MyStatsPackage
]add UnicodePlots
]compat # <1>
```
1. let's directly add a compat entry for UnicodePlots
### Semantic Versioning
Following `semver` - three parts:
`v2.7.5`
means:
- **Major** 2
- **Minor** 7
- **Bugfix** 5
Bump **Major** if you propose backward-breaking changes
Bump **Minor** if you only introduce new features
Bump **Bugfix** if you, well, fix bugs
**Special case:**
`v0.37.1`
Means package is in development and not stable.
Bump **Major** if you release it
Bump **Minor** for breaking changes
Bump **Bugfix** if you fix bugs or release new features
### Compat entries
compat entries define with what versions your package is compatible with
```julia
[compat]
AllMinorReleases1 = "1" # <1>
AllMinorReleases2 = "1.5" #<2>
AllMinorReleases3 = "1.5.3" #<3>
ExactPackage = "=1.5.6" #<4>
MultiVersionexample = "0.5,1.2,2"
DevelopPackage = "0.2.3" # <5>
```
1. [1.0.0-2)
2. [1.5.0-2)
3. [1.5.3-2)
4. [1.5.6]
5. [0.2.3 - 0.3)
As you can see, develop version (`version < 1`) are treated a bit special in Julia, and different to `semver`. [Read more here](https://pkgdocs.julialang.org/v1/compatibility/#compat-pre-1.0)
::: callout-warning
keep the compat list in alphabetical order - github-actions might behave very strange else.
:::
## Projects in Julia
Formally, projects don't have specific requirements. You should activate an environment (`Project.toml`+`Manifest.toml`) in the main folder though. I recommend the following minimal structure:
- `./src/` - all functions should go there
- `./scripts/` - all actual scripts should go here,
- `./README.md` - Write what this is about, who you are etc.
- `./Project.toml` - Your explicit dependencies
- `./Manifest.toml` - Your implicit dependencies + versions <-- this makes it reproducible!
::: callout-tip
One recommendation is to use `DrWatson.initialize_project([path])` to start a new project - it will generate a nice folder structure + provide some other helpful `DrWatson.jl` features.
(click the following tipp to expand the full datastructure)
:::
:::{.callout-tip collapse="true"}
```
│projectdir <- Project's main folder. It is initialized as a Git
