view release on metacpan or  search on metacpan

lib/Bigtop/Docs/Syntax.pod  view on Meta::CPAN

=head1 NAME

Bigtop::Docs::Syntax - An introduction to Bigtop syntax description

=head1 Intro

This document explains the basic structure of a bigtop file.

Note that you might find L<Bigtop::Docs::Cookbook> useful depending on
the complexity of your questions and how you like to use docs.  For a
full list of Bigtop keywords, see L<Bigtop::Docs::FullKeywords>.  A
shorter version is available in L<Bigtop::Docs::QuickKeywords>.
To know what each backend does, and how to configure them, see
L<Bigtop::Docs::AutoBackends>.  All of those, except the cookbook,
are generated from the official source of Bigtop keywords (Bigtop::Keywords)
and so are up to date.

Other docs are available, including docs on tentmaker.  See
L<Bigtop::Docs::TOC> for a complete list of documentation.

=head1 Anatomy of a Bigtop File

Bigtop files are designed to be easy to write and to read (by you and the
computer).  There is a basic structure based on brace delimited blocks,
but it's not complicated like a programming language.  It's a descriptive
language.  There is no flow of control.  That means that you can
put things in whatever order you like, except that config comes first
and some recipients of the generated files may care about order.  For
instance, your command line SQL tool probably expects to see the
definition for a table before it sees any foreign keys pointing to that
table.  These orderings are usually fairly intuitive, especially when that
other program complains about missing definitions, etc.  (Further, if
you use L<Kickstart Syntax>, Bigtop will adjust the order to account
for foreign keys.)

The following skeleton is the smallest legal bigtop file which describes
almost nothing (and will do nothing if you feed it to bigtop):

    config {}
    app App::Name {}

=head2 config Section

At the top level there are two sections in a Bigtop file.  The order is
enforced.  First comes config.  It lists things that make the output
specific.  In it, there are statements and backend blocks.  Each statement
can take exactly one value.  If there are any characters that Perl wouldn't
like in an identifier, enclose the value in back ticks, a.k.a. backquotes,
(the quote usually found under tilde, not the ones on the same key with
double quotes).

The available config statements are described briefly in
L<Bigtop::Docs::QuickKeywords> and in more detail in
L<Bigtop::Docs::FullKeywords>.  There are two keywords which have
been deprecated and so do not appear there.  These are sometimes useful
for testing, so I've described them here:

=over 4

=item base_dir

Deprecated.

Optional, defaults to the current directory.  Ignored with a warning except
in create mode.

A path to where the app will be built.  Enclose paths in backquotes.  Example:

    base_dir `/home/phil/play`;