Add Support for Example Code

[ryukoposting]

This PR adds features for building/running example code.

Rationale

Example code is awesome.

A lot of Nimble packages rely on example code in lieu of extensive documentation. However, different packages structure their examples in different ways, so users have to figure out how to compile/run the examples first. By providing support for example code inside of Nimble, we can create a de facto standard structure for example code, making the Nim ecosystem more accessible.

.nimble files already have a bin variable that contains a list of executables that can be built from the Nimble package. Example code could be added to a Nimble package using bin. However, this is bad practice because the examples could be installed to a user's machine using nimble install. Obviously, installation isn't desirable for example code.

Changes

New examplesDir .nimble variable

A new variable has been added to the .nimble file: examplesDir. It works similarly to srcDir and binDir, except sequences aren't allowed. examplesDir tells Nimble which folder contains the example code.

If examplesDir is not specified, its value is assumed to be "examples".

New --example command-line argument

A new command line argument has been added: --example. It can be used on the run, build, js, cc, and c commands.

When --example is specified, these commands will search for the target file inside of the example directory, instead of searching through the package itself.

Examples:

nimble run --example example1     # build and run examples/example1.nim
nimble build --example example1   # build examples/example1.nim
nimble js --example example1      # compile examples/example1.nim to examples/example1.js

New nimble init behavior for library and hybrid projects

For library and hybrid projects, the .nimble file generated by nimble init will now include this line:

# examplesDir   = "examples"    # Uncomment to change the name of the examples directory

examplesDir is commented out for two reasons:

• The default value is sane.
• Existing Nimble versions throw some really ugly error messages when they encounter variables they don't recognize.

New library projects will now include this file, located at examples/example1.nim:

# You may create as many example files as you want. Example file names should
# be valid Nim module names.
#
# To run this example, simply execute `nimble run --example example1`.

import <package_name>

echo "One plus one equals ", $add(1, 1)

New hybrid projects will now include this file, located at examples/example1.nim:

# You may create as many example files as you want. Example file names should
# be valid Nim module names.
#
# To run this example, simply execute `nimble run --example example1`.

import <package_name>/submodule

echo getWelcomeMessage()

Example

To try out this feature on the fly:

cd <some/nimble/project>
mkdir examples
echo 'echo "Hello, world!"' > examples/my_example.nim
nimble run --example my_example

[dom96]

This is cool, but is effectively a shortcut for nimble run examples/example1. With the --example flag you are writing basically the same thing on the command line, so is it worth it?

I think a more interesting implementation would be implementing support for a command which initialises a script based on an example from a named package. Something like:

$ nimble init-example pkgName/exampleName # creates a exampleName.nim file in the CWD ready to be compiled/edited

[evanperryg-old]

This is cool, but is effectively a shortcut for nimble run examples/example1. With the --example flag you are writing basically the same thing on the command line, so is it worth it?

That's true, but one package might require you to do nimble run example/xyz while another one might require nimble run samples/xyz and so on. --example and examplesDir abstract away this kind of inconsistency, opening the door for features like the one you describe.

I think it's worth noting here that the Nimble readme doesn't actually say exactly where your example code is supposed to go, nor does nimble init currently create a directory for example programs.

[ryukoposting]

@dom96 I played around with it a bit, and it isn't possible to do nimble run foldername/filename without tweaking the .nimble file and/or doing some config.nims shenanigans. Nimble gives you a scaffold for the rest of the package, so I see no reason why it shouldn't give you a ready-made spot for example programs.

However... Are the --example / examplesDir additions putting the cart ahead of the horse? My goal was to make it work, not to fully explore the possibilities of example code in Nimble.

There might be a lot of cool things Nimble could do with examples (like your init-example idea) that I haven't considered. Expanding on your init-example concept could lead us to something resembling a rails generate command built into the language package manager. Is that awesome? Is that harmful?

[ire4ever1190]

Think would be awesome

Would also remove the need for writing custom tools like logue and nicoboot

[ryukoposting]

I've thought about this for a few weeks, and I have some thoughts for how I could make this better:

Things to remove:

Right now, nimble example injects an includePath into the underlying nim c -r command that executes the example. For the sake of consistency, this should be removed. Although this feature eliminates the need for a config.nims in the ./examples folder, it's also inconsistent with the way nimble test works.

Things to add:

Some way to quickly copy/run examples from Nimble packages. Here is my idea:

nimble develop [pkgname] [-e,--example] [examplename] could clone an example from a particular package into the working directory. This would make it easy for users to fiddle with example code, and running an example would be as easy as nimble develop [pkgname] [-e,--example] [examplename]; nim c -r [examplename].

[FedericoCeratto]

@dom96 Nimble does not provide an automated way to generate, package and install developer documentation. Having an examplesDir variable would be a step in the right direction.