|
Home · Reference · User Guide · Internals | |
It's a little non-intuitive but easy enough to fill out.
set_optvar("name", +{
"attribute" => "value",
"attribute" => "value",
});
There are a number of attributes with specific meanings:
Allow this variable to be [un]set from the commandline.
The name of the value the user enters (with set/unset).
List the available values (not for binary options).
Apply this default to the variable if the user does not enter one on the commandline.
The value of the variable.
The data is a non-scalar (currently only '@' is supported).
Override the default argument setting behaviour. The switch name is available as $_[0] and the user value is available as $_[1].
Create set/unset aliases for backwards compatibility reasons. These are not documented in the help.
Used to tell if the option is visible to the user.
Used to tell if the option is suitable for the current configuration.
Indicates an option that was taken from the default or generated. In most cases, this shouldn't need to be set.
Show the user if the default is used (should be used for important options only).
Silently ignore this option if it's not visible.
List the code that should be put into config.pri.
Do not save this option in config.status.
The order that options are presented to the user is based on the order that they appear in configure.
The set and unset attributes are special. The examples here are for set but they also apply to unset.
"set" => [ "switchname", "help for switch" ],
Since opt variables and switches are often named similarly, you can use shorthand:
set_optvar("myopt", +{
"set" => [ "%", "help for switch" ],
"unset" => [ "no-%", "help for switch" ],
});
The % is expanded to the opt name. Any _ in the opt name are converted to - for the switch. User-values work too. You should supply an arg attribute so the user knows what the value is supposed to be.
"set" => [ "add=s", "add a dir" ],
"arg" => "dir",
Arrays are handled too. The user can use the argument multiple times and the array gets added to each time.
"set" => [ "add=s", "add a dir" ],
"arg" => "dir",
"type" => '@',
However, accessing arrays is not straight forward. See below for more info.
Hidden options should use "hidden" as their help.
The simple case is easy.
opt("variable") = "foo";
print "I got ".opt("variable")."\n";
Non-scalar values (eg. arrays) are a bit harder.
my $ref = opt("variable");
push(@$ref, "foo");
print "I got ".join(" ", @$ref)."\n";
You can access indivitual attributes too. This could come in handy if you need to calculate a default.
opt("variable", "default") = 2;
You can create your own attributes. It is recommended to declare your attributes up front, even if you give them an empty value. This is required for lists. Here's some extra attributes being initialised.
"color" => "",
"frobnitz" => [],
Part of the reason for implementing the new opt system was for default value detection and notification. However, there are some caveats here...
If you need to generate a default after the defaults have been assigned, you must do some extra work. I will include an example for the qvfb option since it relies on other options so it can't be figured out until after the defaults have been applied.
If the value is changed from undef then the user needs to know it was an automatic default. Setting the auto attribute to a non-zero value will make this happen.
opt("qvfb") = 1;
opt("qvfb", "auto") = 1;
A caveat here is that list variables will not have a value of undef. Instead they will have a value equal to the reference to an empty list. In other words, don't set auto for a null list!
Variables that are specific to Qtopia or Qtopia Desktop should use the visible and autodep attributes.
set_optvar( "quicklaunch", +{
"set" => [ "%",
"Use the quicklaunch method of speeding up application loading. ".
"Applications that allow it are built as plugins." ],
"unset" => [ "no-quicklaunch",
"Don't use the quicklaunch method of application loading." ],
"default" => 1,
"visible" => sub { $build_core || $build_pda || $build_phone },
"autodep" => sub { opt("edition") },
});
This means that the switches aren't available if you can't build Qtopia and the default value stuff isn't displayed if opt("edition") isn't set (only Qtopia Desktop is being built). These functions can also be used for platform-specific settings.
If an opt variable have no default and the value is not set, it will have an undefined value. This can cause problems if you try to use the variable later. Here's some examples of how this can affect you. Specifically, you should ensure that warnings are not going to be produced.
if ( opt("variable") ) {
# variable has a non-zero, defined value
}
if ( opt("variable") == 1 ) {
# variable has a value of 1 (will warn if the value is undefined)
}
if ( !opt("variable") ) {
# variable has a zero or undefined value
}
if ( !defined(opt("variable")) ) {
# variable has an undefined value
}
if ( defined(opt("variable")) && opt("variable") == 0 ) {
# variable is defined and has a value of 0
}
If your generated default is merely dependant on another option, you can express that in this way.
my %options = ( "foo" => "1", "bar" => "2", "baz" => "3" );
...
"default" => sub { $options{opt_resolve("othervar")} },
"visref" => sub { opt("othervar") },
"autodep" => sub { opt("othervar") },
opt_resolve causes the variable's real or default value to be returned. This is required when othervar might be null while the help is showing (eg. The edition value has a default but it's not yet applied during the help display).
There are some attributes that can take multiple types. All of these can accept a scalar, array or code block.
Scalars are treated as single-item arrays. Code blocks are evaluated in array context.
Arrays are joined with a space. Code blocks are evaluated in scalar context.
This attribute is handled by write_config_pri.
If the option has the config_pri attribute and is visible, it is evaluated as a series of commands.
If the command contains %, it is printed with % replaced by opt("option", "value") and %{foo} replaced by opt("option", "foo").
If the command doesn't contain % it is printed if the value is not null or empty.
You can add flags by prefixing a command with (). The following flags are available:
print the command if the value is null or empty (ie. reverse the logic).
| Copyright © 2007 Trolltech | Qtopia Build System Documentation |