= BepFile =

== Introduction ==

A .bep file is a ''recipe'' that haikuporter uses to fetch, patch, build and install a software package. It is an ASCII file that contains a list of keys with corresponding (lists of) values. Next to being a recipe for haikuporter, it may also give specific information on how to build a particular application on BeOS (see below).

== Syntax ==

=== Comments ===

It is possible to insert comments in the BepFile.
 * the comment should be on a line of it's own
 * the comment should be preceded with a hash (#)
 * there may be whitespace preceding the '#'

=== Key types ===

There are three types of keys in a !BepFile: single-value, list-of-values and shell commands.

The key label is subject to the following rules:
 * the key label must be in all capitals and consist only of letters (A-Z), numbers (0-9) and underscores
 * there may be no whitespace in front of the key label

==== A key with a '''single value''' ====

{{{
KEY = "value"
}}}

The syntax is subject to the following rules:
 * there may be whitespace around the '=', but it is not required
 * the value should be enclosed within double quotes
 * there may be whitespace after the closing quote

==== A key with a '''list of values''' ====

{{{
KEY = "value1
       value2
       value3"
}}}

The syntax is subject to the rules listed above for a single value key, plus the following:
 * one value is entered per line, with the first on the line of the key label
 * every value but the first is indented by whitespace (tabs or spaces)
 * only one set of double quotes encloses the list, as is visible from the example above
 * the closing double quote is on the same line as the last value of the list


==== A key with a '''list of shell commands''' ====

{{{
KEY = {
       line1
       line2
       line3
      }
}}}

The syntax is subject to these rules:
 * the line of the key label ends with an opening brace '{', with nothing following it (except for whitespace)
 * each line is indented by whitespace (tabs or spaces)
 * the closing brace '}' is on on a separate line, preceded by whitespace
 * the lines between the braces are interpreted as a shell script (bash); hence, it is possible to use conditional execution and insert comments using '#' (see below)

=== List of keys ===

The following keys are currently supported in haikuporter:

||Key||Description||Type||Syntax||Mandatory||Default||
||{{{DESCRIPTION}}}||a (short) description of the software package||single, list||text||yes||-||
||{{{MESSAGE}}}||a message that is shown to the user before building||single||text||no||-||
||{{{HOMEPAGE}}}||URI pointing to the official homepage of the software package||single||URI||yes||-||
||{{{SRC_URI}}}||(a list of) URI(s) pointing to the source code archive of the software package||single, list||URI or [wiki:VersionControlURI]||yes||-||
||{{{CHECKSUM_MD5}}}||md5 checksum of the source code archive of the software package||single||text||no||-||
||{{{REVISION}}}||indicates the HaikuPort revision||single||integer ({{{1}}}, {{{2}}}, {{{3}}}, ...)||yes||-||
||{{{STATUS_HAIKU}}}||indicates the status of this port on Haiku||single||status ({{{untested}}}, {{{unstable}}}, {{{stable}}})||no||{{{untested}}}||
||{{{DEPEND}}}||(list of) !HaikuPort(s) this port depends upon||single, list||{{{category/portname >= portversion}}}||no||-||
||{{{BUILD}}}||list of shell commands (script) to execute in order to build the port||shell||shell commands||no||-||
||{{{INSTALL}}}||list of shell commands to execute in order to install the port||shell||shell commands||no||-||
||{{{TEST}}}||list of shell commands to execute the test(s) for the port||shell||shell commands||no||-||
||{{{LICENSE}}}||(list of) license(s) for the port||single, list||text||no||-||
||{{{COPYRIGHT}}}||(list of) copyright(s) for the port||single, list||text||no||-||

BUILD, INSTALL and TEST scripts are plain bash shell scripts. It is possible to do conditional execution or even loops.

An example of a build script is shown below. Notice that it is possible to add comments using a {{{#}}}. It is highly recommended to document anything special you might do inside a BUILD or INSTALL script. This might help people when they are porting other applications.
{{{
BUILD {
	cd xyz-1.0.0
        libtoolize --force --copy --install
        aclocal
        autoconf
	./configure --prefix=`finddir B_COMMON_DIRECTORY \
                --mandir=`finddir B_COMMON_DOCUMENTATION_DIRECTORY`/man
	make
}
}}}

When a key is not listed in the BepFile, haikuporter assumes the default value, or an empty string/list (when no default value is specified above).

Note: It is possible that the names and/or the use of these keys may change as haikuporter evolves. Keys may also be added and removed. When haikuporter gets a release, the key set shall be frozen.