Why use Draupnir Templates?

These templates have in common the project.odin file and the lib directory. These are the core structures that a Draupnir template requires. Following these conventions, many tools can have a common standard and help the community understand quicker and better Odin codebases. For example the Gungnir tool can assume the codebase contains at minimum a project.odin file and a lib directory and start searching for files to document inside the lib directory. This convention simplifies many decisions and make tools more thoughtful and friendly.

Conventions

Draupnir follows some basic structure for applications in Odin.

lib/ directory

lib directory holds your application source code. This directory is broken into subdirectories (packages). For example, the lib/domain directory will be responsible to host all of your business logic and business domain.

It was chosen lib instead of src because the main application project.odin requires this directory as a “library”.

project.odin file

This is a file that identifies our directory as an Odin project. It also contains the main :: proc() declaration. In full template is used to define common data structures such as command line arguments, logger and project.ini configurations.

Execute project.odin

$ odin run .

Ada_Case package names

Package naming doesn’t need to be a mirror of your OS directories. It’s good when it can, but we don’t need to ruin their naming for the sake of the OS system.

For example

└── controllers
    ├── account_controller.odin
    ├── bread_controller.odin
    └── user_controller.odin

Te package must be named like Project_User_Controller, and not project_user_controller. The convention for naming packages is using Ada_Case.

Is recommended to use a project prefix for package names. For example if my project is named Drawings the package names could be Drawings_Circle and Drawings_Triangle, even though the packages could be in deep hierarchy.

package Drawings

main :: proc() {}

Package directories

Package directories can be lowercase or PascalCase. The only exception is the project.odin level directories that always must be lowercase. PascalCase is recommended when the package could conflict with a built in package. For example string, a package with the name String would not conflict. Is left to the developer the convention used, but they must be consistent in the whole project.

Where these conventions comes from?

This convention takes inspiration and ideas from battle tested projects found in other languages and tools such as:

State of the Art

Odin ecosystem seeems to not have an standard way of file and project organization. Let’s analyze a bunch of Odin projects randomly selected:

Podin

Podin

  • https://codeberg.org/mgavioli/podin

Odin Aseprite

Odin Aseprite

  • https://github.com/blob1807/odin-aseprite

Odin Mimalloc

Odin Mimalloc

  • https://github.com/jakubtomsu/odin-mimalloc

Odin HTTP

Odin HTTP

  • https://github.com/laytan/odin-http

A standarization will help the creation of tools such as IDEs, documentation and other developer experience improvements, increase the speed of understanding the codebase by new people and provide a solid structure for making projects with Odin. Using conventions such as the provided by Draupnir will speed up the development efforts of Odin’s ecosystem.