Bigtop::Docs::Syntax is an introduction to Bigtop syntax description.
This document explains the basic structure of a bigtop file.
Note that you might find 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 Bigtop::Docs::FullKeywords. A shorter version is available in Bigtop::Docs::QuickKeywords. To know what each backend does, and how to configure them, see 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 Bigtop::Docs::TOC for a complete list of documentation.
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 "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 {}
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 Bigtop::Docs::QuickKeywords and in more detail in 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:
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`;
app_dir
Deprecated.
Optional, defaults to the h2xs style directory name for your app. Ignored with a warning except in create mode.
A path relative to base_dir where Build.PL, Changes, README, etc. will live. For example, if your app block looks like this:
app MyNS::Apps::Name
the default will be MyNS-Apps-Name under the base_dir. If you wanted extra nesting you could say:
app_dir `MyNS/Apps/Name`;
then bigtop would make those intervening directories for you.
In addition to these hard coded keys, there are backend blocks which depend on what Bigtop:: modules you have installed. These typically generate files on the disk, which could be Perl modules, httpd.confs, etc.
The system is simplistic and best described by an example. Suppose you list
SomeType SomeBackend {}
in the config section. Bigtop will assume the following (yes, I know how dangerous assumptions can be):
You have a package called Bigtop::Backend::SomeType::SomeBackend, defined in the usual way, which is installed on your system. (i.e. There is a file called SomeBackend.pm which defines the package Bigtop::Backend::SomeType::SomeBackend, which lives in the path Bigtop/Backend/SomeType/SomeBackend.pm, relative to an @INC member.)
That package has a method called gen_SomeType which does whatever backends of this type should do (it might make .pm files, .conf files, .sql files etc.). This allows bigtop to call gen_SomeType when the user types:
bigtop file.bigtop SomeType
The distribution comes with a number of these Bigtop::Backends. [ See Bigtop::Docs::AuotBackends for a list. ] If you write a useful one, please send it in so we can include it in a future release. For advice on writing one, see Bigtop::Docs::Modules.
Product's homepage
Requirements:
· Perl
Find us on Google+
