home | help 
bx(1)			     General Commands Manual			   bx(1)

NAME
     bx - shell script and task runner

SYNOPSIS
     bx [options] path [arg...]
     bx [options] task [arg...]
     bx [options] [-- arg...]

DESCRIPTION
     The build2 shell script and task runner executes a script (first form) or a
     task (second and third form) with optional arguments.

     The  first  argument  after options determines whether it is a shell script
     path or a task name. It is considered a script if it contains the directory
     separator or the .bx extension. Otherwise, it is considered  a  task  name.
     Absent first argument means the default task. In this case the -- separator
     must  be  used if you wish to pass arguments to the default task. Note that
     neither the script path nor task name can start with -.

     Note that task running is not yet implemented.

     The recommended first line ("shebang") for an executable script is as  fol-
     lows:

     #! /usr/bin/env bx

OPTIONS
     -v     Print  actual commands being executed. This options is equivalent to
	    --verbose 2.

     -V     Print all underlying commands being executed. This options is equiv-
	    alent to --verbose 3.

     --quiet|-q
	    Run quietly, only printing error messages. This option is equivalent
	    to --verbose 0.

     --verbose level
	    Set the diagnostics verbosity to level between 0 and 6. Level 0 dis-
	    ables any non-error messages while level 6 produces lots of informa-
	    tion, with level 1 being the default. The following additional types
	    of diagnostics are produced at each level:

	    1.	High-level information messages.

	    2.	Essential underlying commands being executed.

	    3.	All underlying commands being executed.

	    4.	Information that could be helpful to the user.

	    5.	Information that could be helpful to the developer.

	    6.	Even more detailed information.

     --diag-color
	    Use color in diagnostics. If printing to a	terminal  the  color  is
	    used  by  default  provided the terminal is not dumb. Use --no-diag-
	    color to suppress.

     --no-diag-color
	    Don't use color in diagnostics.

     --max-stack num
	    The maximum stack size in KBytes to allow for newly created threads.
	    For pthreads-based systems the driver queries the stack size of  the
	    main  thread and uses the same size for creating additional threads.
	    This allows adjusting the stack size using familiar mechanisms, such
	    as ulimit.	Sometimes, however, the stack size of the main thread is
	    excessively large.	As a result, the driver checks if it is  greater
	    than  a  predefined limit (64MB on 64-bit systems and 32MB on 32-bit
	    ones) and caps it to a more sensible value (8MB) if that's the case.
	    This option allows you to override this check with the special  zero
	    value  indicating  that the main thread stack size should be used as
	    is.

     --pager path
	    The pager program to be used to show long text. Commonly used  pager
	    programs  are less and more. You can also specify additional options
	    that should be passed to the pager program with  --pager-option.  If
	    an	empty  string  is  specified as the pager program, then no pager
	    will be used. If the pager program is not explicitly specified, then
	    b will try to use less. If it is not available, then no  pager  will
	    be used.

     --pager-option opt
	    Additional option to be passed to the pager program. See --pager for
	    more information on the pager program. Repeat this option to specify
	    multiple pager options.

     --options-file file
	    Read  additional  options  from file. Each option should appear on a
	    separate line optionally followed by space or equal sign (=) and  an
	    option  value.  Empty  lines  and lines starting with # are ignored.
	    Option values can be enclosed in double (") or single (') quotes  to
	    preserve  leading  and  trailing  whitespaces  as well as to specify
	    empty values. If the  value  itself  contains  trailing  or  leading
	    quotes,  enclose it with an extra pair of quotes, for example '"x"'.
	    Non-leading and non-trailing quotes are interpreted as being part of
	    the option value.

	    The semantics of providing options in a file is equivalent	to  pro-
	    viding the same set of options in the same order on the command line
	    at	the  point  where  the --options-file option is specified except
	    that the shell escaping and quoting is not required. Repeat this op-
	    tion to specify more than one options file.

     --default-options dir
	    The directory to load additional default options files from.

     --no-default-options
	    Don't load default options files.

     --help Print usage information and exit.

     --version
	    Print version and exit.

DEFAULT OPTIONS FILES
     Instead of having a separate config file format for tool configuration, the
     build2 toolchain uses default options files which contain the same  options
     as what can be specified on the command line. The default options files are
     like  options  files  that  one can specify with --options-file except that
     they are loaded by default.

     The default options files for bx are called  bx.options,  bx-script.options
     (shell  script  only), and bx-task.options (task only) and are searched for
     in the .build2/ subdirectory of the home directory and in the system direc-
     tory (for example, /etc/build2/) if configured. Note that	besides  options
     the  bx-task.options  file  can  also contain global variable overrides (@@
     only for task running?).

     Once the search is complete, the files are loaded	in  the  reverse  order,
     that is, beginning from the system directory (if any), followed by the home
     directory,  and  finishing  off  with  the options specified on the command
     line.  For each directory bx.options, if found, is loaded	first,	followed
     by  bx-script.options for a shell script and bx-task.options for a task. In
     other words, the files are loaded from the more generic to  the  more  spe-
     cific with the command line options having the ability to override any val-
     ues specified in the default options files.

     If a default options file contains --no-default-options, then the search is
     stopped  at  the  directory  containing  this  file  and no outer files are
     loaded. If this option is specified on the command line, then none  of  the
     default options files are searched for or loaded.

     An  additional  directory containing default options files can be specified
     with --default-options. Its configuration files are loaded after  the  home
     directory.

     The  order  in which default options files are loaded is traced at the ver-
     bosity level 3 (-V option) or higher.

EXIT STATUS
     In case of a script execution, the script exit code is returned. In case of
     a task execution, non-zero exit status is returned in case of an error.

ENVIRONMENT
     The HOME environment variable is used to determine the user's  home  direc-
     tory.  If	it  is	not set, then getpwuid(3) is used instead. This value is
     used to shorten paths printed in diagnostics by replacing the  home  direc-
     tory  with ~/. It is also made available to scripts as the shell.home vari-
     able.

     The BUILD2_DEF_OPT environment variable is used to suppress loading of  de-
     fault options files in nested runner invocations. Its values are false or 0
     to suppress and true or 1 to load.

BUGS
     Send bug reports to the users@build2.org mailing list.

COPYRIGHT
     Copyright (c) 2014-2026 the build2 authors.

     Permission is granted to copy, distribute and/or modify this document under
     the terms of the MIT License.

build2 0.18.0			   April 2026				   bx(1)
home | help