Concepts

Odyn's model is simple enough to fit in your head. This page explains the moving parts.

The Lockfile

Every dependency you add with odyn get gets an entry in Odyn.lock, with name, source, and a specific commit:

# This file is automatically @generated by Odyn.
# Do not edit this file manually unless you know what you're doing.

[[dep]]
name = "math"
source = "https://github.com/odin-community/math"
commit = "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"

The commit hash is what matters, it's the exact state of the repository at the time you ran odyn get. That's what odyn sync reproduces.

Therefore, Commit Odyn.lock to version control. Without it, odyn sync has nothing to work from.

Pinning

When Odyn pins a dependency, it records the current HEAD commit of the repository. That commit never moves. If the upstream repository changes, your project doesn't, until you explicitly run odyn update <dep> to re-pin to the new HEAD.

Additionally, while get-ting the dependency, you could specify the commit using --commit <hash> so you don't have to write to the lockfile, for cases where you want a specific commit.

odyn get burger/burgberg --commit a1b2c69

odyn_deps/

The odyn_deps/ directory is where Odyn stores the dependencies you added, and is accessible in-code using the deps: collection that was automatically set in ols.json by odyn init.

import "deps:math"

note

While this works on your code editor, building it needs a compiler flag to tell the compiler that "the deps: collection exists and points to odyn_deps/", like so:

# at the root of your project...
odin run src -collection:deps=odyn_deps
#            ^^^^^^^^^^^^^^^^^^^^^^^^^^

It is fully reproducible from Odyn.lock. You can gitignore it, never look at it, or recursively delete it. odyn sync will try its best restore it exactly. The point is, always commit Odyn.lock.

odyn sync

tip

If you're worried whether an upstream repo would be inaccessible in the future, it's recommended to commit odyn_deps/.

Local Repos?

Odyn only accepts remote Git URLs or resolvable shorthands. A local path like ../mylib is machine-specific: it doesn't exist on another machine, which breaks odyn sync for anyone else. Running get on it would produce the following message:

$ odyn get ../mylib
      Getting '../mylib'
        Error local paths aren't supported. push '../mylib' to a Git remote and use that URL instead

If you're developing a library locally alongside a project, commit it to a remote and use odyn get with --commit to pin a specific hash.

note

Alternatively, commit the library with the project.