NAME [edit section]

= NAME =
get_program_path

SYNOPSIS [edit section]

= SYNOPSIS =
 * get_program_path <program_name> [<extra_dirs>]

DESCRIPTION [edit section]

= DESCRIPTION =
This function searches for the indicated program on the target board.
It checks for the program in the board test dir, then in
the directories specified by the PATH on the board.
If a second parameter is provided, the directories in that parameter
are searched as well, BEFORE the directories in the PATH.

So the overall search order is:
 * $BOARD_TESTDIR/fuego.$TESTDIR
 * alternate directories (if specified)
 * PATH directories

If the program is not found, then a default path is returned, of
$BOARD_TESTDIR/fuego.$TESTDIR/<program_name>

This function sets an environment variable with
with the path to the program, which can be used to execute it.
The variable name is the program name,
in upper case, prefixed with the string 'PROGRAM_'.

For example, if the following call were made:

get_program_path ls

``get_program_path ls``

and 'ls' was found on the target board in the PATH (specifically, at /bin/ls),
then get_program_path would return with the
shell environment variable PROGRAM_LS with the value '/bin/ls'.

If the program is not found, then a path is returned that would execute
the program if it were located in the test's directory on the target board.

The purpose of this function is to allow tests to use previously installed
test programs on the target board.  Some labs install test programs prior
to running Fuego tests, and skip the 'deploy' phase when running each test.
This function allows tests to run more easily in those labs.

EXAMPLES [edit section]

= EXAMPLES =
Here are some sample invocations:
{{{#!YellowBox
    get_program_path cyclictest
    report "$PROGRAM_CYCLICTEST $CYCLICTEST_ARGS"
}}}

If found, the environment variable PROGRAM_CYCLICTEST will be set, with the
path on the target board where 'cyclictest' is found.

----
Search with an alternate directory:

{{{#!YellowBox
    get_program_path runltp /opt/ltp
    report "$PROGRAM_RUNLTP $RUNLTP_ARGS"
}}}

In this example, search directories in the following order:
 * $BOARD_TESTDIR/fuego.$TESTDIR
 * /opt/lpt
 * directories on the board's PATH

If found, the environment variable PROGRAM_RUNLTP will be set, with the path
on the target board where 'runltp' is found.

ENVIRONMENT and ARGUMENTS [edit section]

= ENVIRONMENT and ARGUMENTS =
The positional arguments to get_program_path are:
 * $1 - the filename of the program to get the path for
 * $2 - (optional) a colon-separated list of additional directories to check

RETURN [edit section]

= RETURN =
''PROGRAM_<prog_name>'' is set to the path on the target board where
the program should be expected.  Note that when the program is not found,
the default value of '$BOARD_TESTDIR/fuego.$TESTDIR/<program>' is returned.
Thus, just because the program returns with the PROGRAM_* variable set,
the program has not been verified to be present at the indicated path.
In that case, the [[function_report|report]] or
[[function_report_append|report_append]] function will report an error.

SOURCE [edit section]

= SOURCE =
Located in ''scripts/functions.sh''

SEE ALSO [edit section]

= SEE ALSO =
 * [[function_test_run|test_run]], [[function_is_on_target_path|is_on_target_path]], [[function_check_has_program|check_has_program]],
[[function_assert_has_program|assert_has_program]]