Sample flows

This crate and folder contains a number of sample 'flows' that have been developed during the development of the compiler and the run-time to drive the project development and demonstrate it working.

They also serve as a type of regression test to make sure we don't break any of the semantics that the samples rely on.

They range from the extremely simple "hello-world" example to more complex ones like generation of a fibonacci series or a mandlebrot set image.

Structure of each sample

Each sample directory contains:

• A DESCRIPTION.md file that:
  • describes what the Flow does
  • lists the features of flow that this sample uses and demonstrates
• A root.toml file that is the root file of the flow description
• Files used in the automated testing of each sample:
  • test_arguments.txt the arguments to be passed to the flow when running it
  • test_input.txt the input supplied to the flow when running it
  • expected_output.txt the output that the flow is expected to produce when invoked with text_arguments.txt and input test_input.txt

Compiling the Samples

The samples set has now been converted to a rust crate with a custom build script.

There is no dependency declared in Cargo.toml on the other crates (as you cannot currently declare a dependency on a binary, just a lib), but in order to build, test and run this crate/folder you will need flowc and flowr installed and on $PATH in order for build scripts to find them.

Using cargo build -p flowsamples causes the build script to run, and it compiles in-place the samples using the flowc compiler.

Running the Samples

Using cargo run -p flowsamples causes the sample runner in main.rs to run. It looks for sub-folders in the samples folder and then executes the sample within.

When running them, it uses:

• test.arguments - arguments passed to the flow on the command line when executing it
• test.input - test input to send to the sample flow using STDIN

The output is sent to standard output.

To run a specific sample only use cargo run -p flowsamples {sample-name}

Testing the Samples

You can test all samples by using cargo test -p flowsamples, it will run each one in turn with the pre-defined arguments and standard input.

It also gathers the standard output, standard error and files generated and checks for correctness by comparing them to previously generated content distributed with the package.

• If there is any standard error found in the file test.err then the test will fail.
• If there is no standard error then it compares standard output captured in test.output to expected.output and fails if there is a difference.
• If an expected.file exists then it compares it to file output in test.file and fails if there is any difference with the expected file.

cargo test -p flowsamples 
    Finished test [unoptimized + debuginfo] target(s) in 0.11s
     Running target/debug/deps/samples-9e024e2c420db146


running 16 tests
test test::test_all_samples ... ignored
test test::test_args ... ok
test test::test_arrays ... ok
test test::test_factorial ... ok
test test::test_fibonacci ... ok
test test::test_hello_world ... ok
test test::test_mandlebrot ... ok
test test::test_matrix_mult ... ok
test test::test_pipeline ... ok
test test::test_prime ... ok
test test::test_primitives ... ok
test test::test_sequence ... ok
test test::test_sequence_of_sequences ... ok
test test::test_reverse_echo ... ok
test test::test_router ... ok
test test::test_tokenizer ... ok




test result: ok. 15 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out
test result: ok. 15 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out

NOTE: Until multiple instances of the client/server pair for running flows can be run at once, we need to restrict the test framework to only run one test at a time, otherwise by default it will run multiple tests at once, and some will fail.

NOTE: At the moment, to make the progress more visible, each sample has a test manually added to it in samples/main.rs, so for a new sample a test needs to be added by the author.

To test just one sample use cargo test -p flowsamples {test-name}

cargo test -p flowsamples test_factorial
    Finished test [unoptimized + debuginfo] target(s) in 0.12s
     Running target/debug/deps/samples-9e024e2c420db146


running 1 test
test test::test_factorial ... ok




test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 15 filtered out
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 15 filtered out

Default workspace member crate

The samples crate is one of the default-members of the flow workspace project, so it is used if no particular package is supplied, thus the samples can also be built and run using:

• cargo build : compile the samples using flowc
• cargo run : run the samples using flowr
• cargo test : run the samples using flowr and check the generated output is correct

As other default-members are added to the workspace over time, those commands may do other things, so just be aware that if you only want to run the samples the -p samples option above will be safer.

flowsamples executable

There is also an executable (bin or binary) installed with the library called flowsamples that if run without any arguments will run all the samples. You can supply it the name of a sample (the name of the folder under samples where the sample is) to run just that one sample.

Developing a new sample

To develop a new sample, just create a new folder under 'samples' with your sample name.

Add the root.toml and any other included flows and describe them.

Add a DESCRIPTION.md file that describes what the sample does and what features of flow it uses.

Add an entry in the guide's "samples" section that will include the DESCRIPTION.md file above.