Qtopia Home · Home · Reference · User Guide · Internals

Opt System

This document describes the opt system, used to decide which options are available in configure.

Defining a new opt variable

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:

The order that options are presented to the user is based on the order that they appear in configure.

set/unset

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.

Accessing variables

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;

Extra attributes

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" => [],

Default values

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!

Conditional defaults

Variables that are specific to Qtopia or Qtopia Sync Agent 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 Sync Agent is being built). These functions can also be used for platform-specific settings.

Undefined values

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
    }

Computed defaults

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).

Attributes that take multiple types

There are some attributes that can take multiple types. All of these can accept a scalar, array or code block.

config_pri

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:


Copyright © 2008 Nokia Qtopia Build System Documentation