Improvements and explanations in dynlib example

[macsmol]

While learning how to load a *.dll I studied \ODIN\core\dynlib\example\example.odin
I've run into two small issues while trying to run the example:

1. The package name in example.odin does not compile as it is.
2. The DLL needs to be build first (and with a correct name) for the example.dll to work.

I hope this PR helps with these two.

[Kelimion]

This change is unnecessary, and actually confuses things as example.odin isn't a library or part of the same package as lib.odin, it is the example that loads said library. And -file means that the different package names in the same directory don't clash, as each file is considered its own package.

It works just fine if you build lib.odin with -file followed by example.odin also using -file.

This is what I have in my build.bat (not in the repo):

odin build lib.odin -file -build-mode:dll -vet
odin run example.odin -file -vet

[Kelimion]

My suggestion is to revert the changes to both files, and instead add a doc.odin file. Something along these lines.

/*

This directory comprises two distinct packages:
- `lib.odin` is dynamic library exporting a number of symbols.
- `example.odin` is a separate package, demonstrating how to dynamically load the symbols in `lib.odin`.

To try this out, first compile `lib.odin`, like so:
- `odin build lib.odin -file -build-mode:dll`

Then build and run the example package:
- `odin run example.odin -file`.

If everything goes well, you should see output resembling the following (the addresses may differ):

(Initial DLL Load) ok: true. 3 symbols loaded from lib.dll (0x7FFB3DD90000).
42 + 42 = 84
84 - 13 = 71
hellope = 42
(DLL Reload) ok: true. 3 symbols loaded from lib.dll (0x7FFB3DD90000).
42 + 42 = 84
84 - 13 = 71
hellope = 42

*/
package dynlib_example_documentation

[macsmol]

Oh that's interesting! I wish I knew that!
Your idea seems fine to me. I'll push the PR.

On the side note.
It's not the first time that I run into friction due to not understanding how packages work.
While trying to run raylib
https://github.com/odin-lang/examples/tree/master/raylib/ports/textures
I bulk renamed all the files in folder (except one) from .odin -> odin.off as a workaround to compilation errors.
Only now I've found an explanation in
https://github.com/odin-lang/examples/blob/master/raylib/ports/README.md

Maybe this behaviour could be mentioned in https://odin-lang.org/docs/overview/#packages ?
It does not suggest anything about compiling single file.

[Kelimion]

Yes, I think we can do that.

[Kelimion]

Funnily enough, at the very start of the overview, it did already mention this feature of packages.

[macsmol]

Hmmm..
So this is explained in the docs after all. I'm not sure how to explain this better.
Few thoughts: when I've run into I was just thinking: "how do I get rid of this compilation error?"*

• There are two types of these that I've run into:

1. about conflicting package names:

EXAMPLES_ROOT/raylib/ports/textures/textures_gif_player.odin(1:1) Syntax Error: Different package name, expected 'raylib_examples', got 'main'

2. about duplicate main() procedures:

[...]
EXAMPLES_ROOT/raylib/ports/textures/textures_npatch_drawing.odin(27:1) Error: Redeclaration of 'main' in this scope 
	at EXAMPLES_ROOT/raylib/ports/textures/textures_background_scrolling.odin(23:1) 
	main :: proc() { 
	^ 
EXAMPLES_ROOT/raylib/ports/textures/textures_bunnymark.odin(32:1) Error: Redeclaration of the entry pointer procedure 'main' 
	main :: proc() { 
	^ 
[...]

Two suggestions that come to my mind are:

1. Move the paragraph you mentioned to the bottom "packages" section. Hopefully this way one will have better understanding of the subject matter to appreciate that paragraph.
2. Make the two error messages more verbose. Add the suggestion about single file compilation?

[Kelimion]

I already added mention of -file under the Packages header.

[Kelimion]

Hinting at -file in the compilation errors is a good shout.

[Kelimion]

Incoming patch:

[macsmol]

I've pushed the changes you suggested