Adding LALRPOP to your Cargo.toml
file
LALRPOP works as a preprocessor that is integrated with cargo. When
LALRPOP is invoked, it will search your source directory for files
with the extension lalrpop
and create corresponding rs
files. So,
for example, if we have a file calculator.lalrpop
, the preprocessor
will create a Rust file calculator.rs
. As an aside, the syntax of
LALRPOP intentionally hews fairly close to Rust, so it should be
possible to use the Rust plugin to edit lalrpop files as well, as long
as it's not too picky (the emacs rust-mode, in particular, works just
fine).
To start, let's use cargo new
to make a new project. We'll call it
calculator
:
> cargo new --bin calculator
We now have to edit the generated calculator/Cargo.toml
file to invoke the LALRPOP preprocessor. The resulting file should
look something like:
[package]
name = "calculator"
version = "0.1.0"
authors = ["Niko Matsakis <niko@alum.mit.edu>"]
[build-dependencies] # <-- We added this and everything after!
lalrpop = "0.19.7"
[dependencies]
lalrpop-util = "0.19.7"
regex = "1"
Cargo can run build scripts as a pre-processing step,
named build.rs
by default. The [build-dependencies]
section specifies the dependencies for build scripts -- in this
case, just LALRPOP.
The [dependencies]
section describes the dependencies that LALRPOP
needs at runtime. All LALRPOP parsers require at least the
lalrpop-util
crate. In addition, if you don't want to write the
lexer by hand, you need to add a dependency on the regex crate. (If
you don't know what a lexer is, don't worry, it's not important just
now, though we will cover it in the next section; if you do
know what a lexer is, and you want to know how to write a lexer by
hand and use it with LALRPOP, then check out the lexer tutorial.)
Next we have to add build.rs
itself. For those unfamiliar with this feature, the build.rs
file
should be placed next to your Cargo.toml
file and not inside the src
folder with the rest of
your Rust code. This should just look like the following:
extern crate lalrpop; fn main() { lalrpop::process_root().unwrap(); }
The function process_root
processes your src
directory, converting
all lalrpop
files into rs
files. It is smart enough to check
timestamps and do nothing if the rs
file is newer than the lalrpop
file, and to mark the generated rs
file as read-only. It returns an
io::Result<()>
, so the unwrap()
call just asserts that no
file-system errors occurred.
NOTE: On Windows, the necessary APIs are not yet stable, so timestamp checking is disabled.