= BepFile =

== Introduction ==

A .bep file is a ''recipe'' that BePorter 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 BePorter, 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 seperate 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 BePorter:

||Key||Description||Type||Syntax||Mandatory||Default||
||{{{DESCRIPTION}}}||a (short) description of the software package||single, list||text||yes||-||
||{{{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||yes||-||
||{{{REVISION}}}||indicates the BePort revision||single||integer ({{{1}}}, {{{2}}}, {{{3}}}, ...)||yes||-||
||{{{STATUS_R5}}}||indicates the status of this port on BeOS R5||single||status ({{{untested}}}, {{{unstable}}}, {{{stable}}})||no||{{{untested}}}||
||{{{STATUS_BONE}}}||indicates the status of this port on BeOS BONE/Dano and Zeta||single||status ({{{untested}}}, {{{unstable}}}, {{{stable}}})||no||{{{untested}}}||
||{{{STATUS_HAIKU}}}||indicates the status of this port on Haiku||single||status ({{{untested}}}, {{{unstable}}}, {{{stable}}})||no||{{{untested}}}||
||{{{DEPEND}}}||(list of) !BePort(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||-||

BUILD and INSTALL scripts are plain bash shell scripts. It is possible to do conditional execution or even loops. For example, it is possible to distinguish between the different BeOS platforms using the {{{BEPORTS_PLATFORM}}} environment variable. It can be one of {{{R5}}}, {{{BONE}}} or {{{HAIKU}}}. BePorter detects which BeOS platform it is running on and set the {{{BEPORTS_PLATFORM}}} variable accordingly.

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
	if [ "$BEPORTS_PLATFORM" = "BONE" ] ; then
		export EXTRA_CONFARGS="--enable-debug"	# some problems on BONE because of ...
	else
		export EXTRA_CONFARGS=""
	fi
	./configure --prefix=/boot/home/config $EXTRA_CONFARGS
	make
}
}}}

When a key is not listed in the BepFile, BePorter 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 BePorter evolves. Keys may also be added and removed. When BePorter gets a release, the key set shall be frozen.