# Running Little Rust Snippets
## Leaving the Comfort (and Restrictions) of Cargo
Cargo is a good, reliable way to build programs and libraries in Rust with versioned dependencies.
Those who have worked with the Wild West practices of C++ development find this particularly soothing,
and it's frequently given as one of the strengths of the Rust ecosystem.
However, it's not intended to make running little test programs straightforward - you have to
create a project with all the dependencies you wish to play with, and then edit `src/main.rs` and
do `cargo run`. A useful tip is to create a `src/bin` directory containing your little programs
and then use `cargo run --bin NAME` to run them. But there is a better way; if you have such
a project (say called 'cache') then the following invocation will compile and link
a program against those dependencies (`rustc` is an unusually intelligent compiler)
```
$ rustc -L /path/to/cache/target/debug/deps mytest.rs
```
Of course, you need to manually run `cargo build` on your `cache` project whenever new dependencies
are added, or when the compiler is updated.
The `runner` tool helps to automate this pattern. It also supports _snippets_, which
are little 'scripts' formatted like Rust documentation examples.
```
$ cat print.rs
println!("Hello, World!")
$ runner print.rs
Hello, World!
```
You can even - on Unix platforms - add a 'shebang' line to invoke runner:
```
$ cat hello
#!/usr/bin/env runner
println!("Hello, World!");
$ ./hello
Hello, World!
```
`runner` adds the necessary boilerplate and creates a proper Rust program in `~/.cargo/.runner/bin`,
prefixed with a prelude, which is initially:
```rust
#![allow(unused_imports)]
#![allow(dead_code)]
use std::fs;
use std::fs::File;
use std::io;
use std::io::prelude::*;
use std::env;
use std::path::{PathBuf,Path};
#[allow(unused_macros)]
macro_rules! debug {
($x:expr) => {
println!(\"{} = {:?}\",stringify!($x),$x);
}
}
```
After first invocation of `runner`, this is found in `~/.cargo/.runner/prelude`;
you can edit it later with `runner --edit-prelude`.
`debug!` saves typing: `debug!(my_var)` is equivalent to `println!("my_var = {:?}",my_var)`.
`--no-prelude` (`-N`) prevents this from being included.
## Adding External Crates
As you can see, `runner` is very much about playing with small code snippets. By
default it links the snippet _dynamically_ which is significantly faster. This
hello-world snippet takes 0.34s to build on my machine, but building statically with
`runner -s print.rs` takes 0.55s.
In both cases, the executable goes into the same directory as the expanded code - but
the dynamically-linked version can't be run standalone unless you make the Rust runtime
available globally.
The static option is much more convenient. You can easily create a static
cache with some common crates:
```
$ runner --create 'time json regex'
```
You can add as many crates if you like - number of available dependencies doesn't
slow down the linker. Thereafter, you may refer to these crates in snippets:
```rust
// json.rs
extern crate json;
let parsed = json::parse(r#"
{
"code": 200,
"success": true,
"payload": {
"features": [
"awesome",
"easyAPI",
"lowLearningCurve"
]
}
}
"#)?;
println!("{}",parsed);
```
And then build statically and run (any extra arguments are passed to the program.)
```json
$ runner -s json.rs
{"code":200,"success":true,"payload":{"features":["awesome","easyAPI","lowLearningCurve"]}}
```
You can use `?` in snippets instead of the ubiquitous and awful `unwrap`, since the boilerplate
encloses code in a function that returns `Result<(),Box<Error>>` which is compatible with
any error return.
`runner` provides various utilities for managing the static cache:
```
$ runner -h
Compile and run small Rust snippets
-s, --static build statically (default is dynamic)
-O, --optimize optimized static build
-e, --expression evaluate an expression
-i, --iterator evaluate an iterator
-n, --lines evaluate expression over stdin; 'line' is defined
-x, --extern... (string) add an extern crate to the snippet
-X, --wild... (string) like -x but implies wildcard use
Cache Management:
--create (string...) initialize the static cache with crates
--add (string...) add new crates to the cache (after --create)
--edit edit the static cache Cargo.toml
--build rebuild the static cache
--doc display documentation
--edit-prelude edit the default prelude for snippets
--alias (string...) crate aliases in form alias=crate_name (used with -x)
Dynamic compilation:
-P, --crate-path show path of crate source in Cargo cache
-C, --compile compile crate dynamically (limited)
--cfg... (string) pass configuration variables to rustc
--libc link dynamically against libc (special case)
<program> (string) Rust program, snippet or expression
<args> (string...) arguments to pass to program
```
You can say `runner --edit` to edit the static cache `Cargo.toml`, and `runner --build` to
rebuild the cache afterwards. The cache is built for both debug and release mode,
so using `-sO` you can build snippets in release mode. Documentation is also built
for the cache, and `runner --doc` will open that documentation in the browser. (It's
always nice to have local docs, especially in bandwidth-starved situations.)
If you want docs for a specific crate, then `runner --doc crate` will work.
But remember that the Rust documentation generated has a fast offline searchable
index!
## Dynamic Linking
It would be good to provide such an experience for the dynamic-link case, since
it is faster. There is in fact a dynamic cache as well but support for linking
against external crates dynamically is very basic. It works fine for crates that
don't have any external depdendencies, e.g. this creates a `libjson.so` in the
dynamic cache:
```
$ runner -C json
```
And then you can run the `json.rs` example without `-s`.
The `--compile` action takes three kinds of arguments:
- a crate name that is already loaded and known to Cargo
- a Cargo directory
- a Rust source file - the crate name is the file name without extension.
Dynamic linking is not a priority for
Rust tooling at the moment. So we have to build more elaborate libraries without the
help of Cargo. (The following assumes that you have already brought in `regex` for a Cargo project,
so that the Cargo cache is populated, e.g. with `runner --add regex`)
```
runner -C --feature default --feature use_std libc
runner -C --libc memchr
runner -C --libc thread-id
runner -C --feature std void
runner -C utf8-ranges
runner -C unreachable
runner -C aho-corasick
runner -C lazy_static
runner -C thread_local
runner -C regex-syntax
runner -C regex
```
This script drives home how tremendously irritating life in Rust would be without Cargo.
We have to track the dependencies, ensure that the correct default features are enabled in the
compilation, and special-case crates which directly link to `libc`.
However, the results feel worthwhile. Compiling the first `regex` documented example:
```rust
extern crate regex;
use regex::Regex;
let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap();
assert!(re.is_match("2014-01-01"));
```
With a static build (`-s`) I get 0.90s on this machine, and 0.47s with dynamic linking.
On my souped-up office machine, it's 0.62s versus 0.32s.
A useful trick - if you want to look at the `Cargo.toml` of an already downloaded crate
to find out dependencies and features, then this command will open it for you:
```
favorite-editor $(runner -P some-crate)/Cargo.toml
```
## Rust on the Command-line
There are a few Perl-inspired features. The `-e` flag compiles and evaluates an
_expression_. You can use it as an unusually strict desktop calculator:
```
$ runner -e "10 + 20*4.5"
error[E0277]: the trait bound `{integer}: std::ops::Mul<{float}>` is not satisfied
--> temp/tmp.rs:20:22
|
will give you its local documentation.
However, it can't be compiled directly, for two reasons:
- `extern crate filetime` is implicit
- `use std::fs` is already in the runner prelude.
So we need to say:
```
$ runner -s --no-prelude --extern filetime filetime.rs
1506778536.945440909s
1506778536
945440909
1506778536
```
Or if you're in a hurry: `runner -sNx filetime filetime.rs`.
You can now compile `filetime` dynamically, but you need to explicitly
ask for the `libc` crate (a special case due to conflict with an unstable
library feature.)
```
$ runner -C -xlibc filetime
```
Then it's possible to run with `-Nx filetime`; this takes about two-thirds of the
static build time.
You will also need this trick when exploring the useful but unsafe `libc`
crate itself:
```rust
$ runner -xlibc -e 'unsafe { libc::isatty(libc::STDOUT_FILENO) }'
1
```