I’m sharing this Discord Message from someone that was doing their best to fill in their gaps in understanding Odin after reading the Overview documentation on odin-lang.org.

This was somewhat confusing, I could change the package foo at the top of the file and it makes no difference and everything works.

From reading this Server, I learned a lot, like this:

• 1 - The package is only linked to the directory name (folder) and nothing else, except;
• 2 - The files in the package directory must all have the same package foo header with the same name, but it does not have to be the same as the package directory name, just unique (see below); and
• 3 - No two packages can have the same directory/folder name (globaly unique); and
• 4 - No two packages can have the same package foo header names (i.e., must be globally unique but not tied to any package (directory) name needed - but would be a good idea, I mean why not…);
• 5 - You cannot have cyclical imports - ever;
• 6 - The package foo header seems powerless for the most part as far as programmer use, but I read it is used by the ABI as a prefix for symbols in the final binary;
• 7 - Sub-packages do not exist, so even nested directories are standalone packages and also do not infer dependence;
• 8 - In Odin you should put as much in one package as possible and do not use packages for namespaces since it will not work (see using) and do not use packages to organize your files, see 9 for proper reason to use packages;
• 9 - Use separate packages only as reusable (stand alone) libraries;
• 10 - Organize files within a package directory by their filenames (ala Java) and not subdirectors for all the reasons above; which is what I will do using snake case for the file names.

If I blew it above let me know.

imho the Overview would do better to include a little more detail like some of the stuff above. When I searched this server I found a huge amount of the above and just cobbled it together from 6-7 posts. I think what was not clear from the overview was: 1, 5, 6, 7 (its there but not clear), 9. It is clear that many people are confused by this, but on the bright side searching the Discord was very useful.

gingerBill indicated this is a common source of confusion for newcomers to Odin:

package name has nothing to do with the thing you import.

This is probably one of the most confusing things about Odin’s packages. The exist for stable ABI and consistent linking names.

Hopefully, I can create a minimum working example that can be illustrative for others and have a PR merged into the Overview documentation. Until then I just want something that can be found outside of Discord for other learners.