= NAME =
assert_has_program

= SYNOPSIS =
 * assert_has_program <program_name>


= DESCRIPTION =
This function checks that the indicated program is present on the target board.  It checks for the program in the directories specified by the PATH on the board.  If the program is not found the currently running test is aborted,
with a message indicating that the program is missing.

If this function is successful, it sets an environment variable
with the path to the program.  The variable name is the program name,
in upper case, prefixed with the string 'PROGRAM_'.

For example, if the following call were made:

``assert_has_program ls``

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

The main purpose of this function is to check that auxiliary programs
that are required by the test are present.  Usually, calls to 'assert_has_program' will be put in the [[function_test_pre_check|test_pre_check]] function of a test.

Use the function [[function_check_for_program|check_for_program]] to determine
if a program is on the board, without aborting the job if it is not found.

= EXAMPLES =
Here are some sample invocations:
{{{#!YellowBox
    assert_has_program atq
}}}

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

{{{#!YellowBox
    assert_has_program expect
}}}

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


= ENVIRONMENT and ARGUMENTS =
The positional arguments to assert_has_program are:
 * $1 - the filename of the program to check for the presence of


= RETURN =
Returns non-zero on error.

''PROGRAM_<prog_name>'' is set to the path on the target board where
the program is found.

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

= SEE ALSO =
 * [[function_test_pre_check|test_pre_check]], [[function_is_on_target_path|is_on_target_path]], [[function_assert_define|assert_define]],
[[function_check_has_program|check_has_program]],
[[function_get_program_path|get_program_path]]