Provided by: golf_601.4.41-1_amd64 
NAME
gg - (golf-compiler-and-utility)
PURPOSE
Golf general purpose utility: build, test, run, miscellaneous (pronounced "gigi").
SYNTAX
gg <options>
DESCRIPTION
COMMAND-LINE OPTIONS
• -k <app name> Create Golf application <app name> with default settings (see mgrg with "-i" option
on creating applications with non-default settings). The default settings mean that your application
is owned by the currently-logged on Operating System user (see "-u" option in mgrg), and that a Unix
socket connecting to your application server isn't restricted by any group (see "-r" option in mgrg).
You must have sudo privilege to create an application (this is the only option that requires it).
This option does nothing if the application already exists. You can combine this option with "-q" to
create and then build an application in the same step.
• -q Build Golf application from source code in the current directory. mgrg must run first in this
directory with "-i" option to create the application. You must have at least one Golf source file
(.golf file), with each such file implementing a single request handler. All application source files
must be contained in a flat directory; however, each request handler can handle any hierarchical
path, so your API can be fully hierarchical.
The following options can be used when building an application:
• --db="<database vendor>:<db config file> ..." Specify a list of databases used in your
application. Each element of the list is <database vendor> (which is 'mariadb', 'postgres' or
'sqlite'), followed by a colon (:) and then <db config file>, where <db config file> is used to
refer to a database in statements such as run-query.
Each <database vendor>:<db config file> is separated by a space. You can list any number of
databases for use in your application. A file in current directory with name <db config file>
must exist and contain the connection parameters for database access, and is copied to Golf's
database configuration directory (see directories). See database-config-file for more details on
the content of this file.
• --lflag=<linker flags> If you wish to add any additional linker flags (such as any non-Golf
libraries), specify them quoted under this option.
• --cflag=<C flags> If you wish to add any additional C compiler (gcc) flags, specify them quoted
under this option.
• --trace If specified, tracing information code will be generated (without it, tracing is not
available and trace-run statement is ignored). Tracing only works when debugging mode is enabled,
so --debug option must be used as well.
• --path=<application path> This option lets you specify the application path for your request
URLs. It is a leading path of a URL prior to request name and any parameters. If empty, the
default is the application name preceded by a forward slash:
/<app name>
• --maxupload=<max upload size> Specify maximum upload size for a file (in bytes). The default is
approximately 25MB.
• --max-errors=<max errors> During building of C code precompiled from .golf source code, gcc
will emit a maximum of <max errors> diagnostic messages per .golf source file. The default is 5.
Note that Golf precompiler stops after the first error in most cases and this setting doesn't
apply to it.
• --debug Debugging information is always included in Golf executables, even if in separate .dbg
(or .debug) files. "--debug" flag is only necessary if tracing is used (see trace-run), as well
as to include additional run-time checks. Do not use "--debug" unless you are a Golf upstream
developer or maintainer, because it may significantly lower the run-time performance.
• --c-lines Skip generating line information when compiling .golf files. By default line
information is included, which allows errors to be reported with line numbers in .golf files. If
you want only generated C code line numbers to be used, use this option. This output will omit
certain color-coded and other details that are normally present without this option.
• --public Change the default behavior of request handler safety so that request handlers without
"public" or "private" clause are by default "public"; see begin-handler for more details.
• --single-file A request handler is written in a source file whose path matches fully or
partially that of the request, and such a file can contain any number of request handlers that
match, see request. If, however "--single-file" is used, each request has to be in its own file
whose path matches fully the request path, and no other request can be implemented in such file.
For example, with "--single-file", request "/myreq" has to be in file "myreq.golf" in the source
directory, while request "/other/newreq" has to be in file "other/newreq.golf" (meaning in file
"newreq.golf" in subdirectory "other" in the source directory).
• --exclude-dir By default, all ".golf" files (including in all subdirectories regardless of how
many levels there may be), are picked up for compilation. If "--exclude-dir" is used, then you
can specify any number of subdirectories, separated by commas, to be excluded.
• --ignore-warn Do not display any warnings during compilation of a Golf application.
• --parallel=<threads> Use <threads> number of threads to compile application. By default, the
number of threads is equal to the number of CPUs (including virtual), allowing each CPU to
compile one source files at a time; this is usually the fastest way. You can serialize
compilation with "--parallel=1"; or you can set <threads> to any number between 1 and three time
the number of CPUs in order to reach your performance and CPU utilization goals.
• --posix-regex Use ERE (Extended Regular Expression) POSIX regex library built into Linux
instead of default PCRE2, see match-regex. While the two are largely compatible, you can use
either one depending on your needs.
• --plain-diag Do not use color-coded and more detailed Golf diagnostic output. While rare, you
may need this option in cases when there may be a Golf or underlying compiler bug, or for some
other reason.
• -c,--clean Clean all object and other intermediate files, so that consequent application build
is a full recompilation. Use it alone and prior to rebuilding the application.
Note that when any gg compilation options change, the application is rebuilt (i.e. the change has the
effect of "--clean").
• -i Display both include and linking flags for an application that uses Client-API to connect to
Golf service. The flags are for C compiler (gcc). If "--include" option is used in addition, then
only include flags are displayed. If "--link" option is used in addition, then only linking flags are
displayed. Use this to automate building of client applications with tools like Makefile.
• -v Display Golf version as well as the Operating System version.
• -s Trace the execution of gg utility and display all the steps in making your application.
• -e <num of errors> Show the last <num of errors> from the backtrace file, which receives error
message and stack trace when program crashes or report-error is issued. Also display the path to
backtrace file which contains the stack details.
• -t <num of trace files> Show the last <num of trace files> most recent trace files for the
application. This is useful when tracing (see trace-run) to quickly find the trace files where Golf
writes to. Also display the path to backtrace file which contains the stack details.
• -o Show documentation directory - web page documentation is located here in the form of a
golfdoc.html file.
• -g Show Golf root directory (i.e. where Golf is installed, see directories).
• -l Show library directory - Golf's libraries and v1 code processor are located there.
• -r [ --req="/<request name>[<url parameters>]"
[ --app="application path" ]
[ --service [ --remote="server:port" ] [ --socket="socket path" ] ]
[ --method="<request method>" ]
[ --content="<input file>" --content-type="<content type>" ]
[ --silent-header ]
[ --arg="<arguments>" ]
[ --exec ] Run a command-line program, or make a service request, or display bash code to do the
same for use in scripts.
If you are not in application's source code directory, then you must specify "--app" option to supply
the application path (typically "/<application name>", see request). You can use "--req" option to
specify the request name and optional URL parameters (see request), for example it may be:
gg -r --req="/encrypt" --exec
to execute request "encrypt", or
gg -r --req="/encrypt/data=somedata?method=aes256" --exec
where "/encrypt" is the request name, and "/data=somedata?method=aes256" represents the URL
parameters.
Use --method to specify the HTTP request method, for instance:
gg -r --req="/encrypt/data=somedata?method=aes256" --method=POST --exec
If not specified, the default method is "GET".
If "--service" is not used, then command-line program will execute and you can specify program
arguments with "--arg" option, in which case "<arguments>" is a string (double or single quoted) that
contains any number of program arguments. To specify arguments for a service see "-a" option in mgrg.
If "--service" is used, then application server will be contacted to execute a service; in this case
if "--remote" is not specified, a local Unix socket is used to contact the server; otherwise
"server:port" specified in "--remote" is the IP/name and port of the server to call, separated by a
colon (":"). In case of a local Unix socket, the socket path is by default "/var/lib/gg/<app
name>/sock/sock", where "/<app name>" is given by the last path segment in "--app" option, or if not
specified it is derived from the name of a Golf application built in the current directory; otherwise
the socket path is given by "--socket" option.
By default, the output in any case will have the HTTP headers. If you don't want those to appear, use
"--silent-header" option.
If "--content" is used, then file <input file> is either piped to the standard input of a command-
line program (if "--service" is not used), or sent as a content to the application server (if
"--service" is used). You can also specify content type with "--content-type". For example:
gg -r -app="/my_app" --req="/some_request?par1=val1&par2=20&par3=4" --method=PATCH --content=something.json --content-type=application/json --exec
Examples of using "-r" option to execute command-line program or to call a service:
#Execute current application as a command-line program, request "json"
gg -r --req="/json" --exec
#Execute application "app_name", service "json" by calling the application server running with a Unix socket
gg -r --req="/json" --app="/app_name" --service --exec
#Execute application "app_name", service "json" by calling the application server running with a Unix socket (specified explicitly)
#Request has input parameter "act" with value "perf"
gg -r --req="/json?act=perf" --app="/app_name" --service --socket="/sock_path/sock" --exec
#Execute application "app_name", service "json" by calling the application server running with a TCP socket on port 2301
#Request has input parameter "act" with value "perf"
gg -r --req="/json/act=perf" --app="/app_name" --service --remote="192.168.0.21:2301" --exec
- Performance
"gg -r" can be used both for testing and in production, however for maximum performance, skip
"--exec" option to display direct bash code that you can copy and paste to use in production. This
direct code is about 300% faster than using "gg -r"; keep this in mind if performance of using "gg
-r" is important. When "--exec" is not used, the output may look like this:
export CONTENT_TYPE=
export CONTENT_LENGTH=
unset GG_SILENT_HEADER
export GG_SILENT_HEADER
export REQUEST_METHOD=GET
export SCRIPT_NAME="/enc"
export PATH_INFO="/encrypt/data/somedata"
export QUERY_STRING="method=aes256"
/var/lib/gg/bld/enc/enc
If you copy the above and paste into bash shell, it will execute the command line program which
handles the request specified (which gg would do when "--exec" is specified, but not as fast). Note
that SCRIPT_NAME will be set to whatever application path you use (i.e. the default or if set with
"--path" option when making the application; or with "--app" option here), see request.
If you need to have run-time parameter(s) to "gg -r", escape them when displaying the direct bash
code and run with "eval", for instance:
COMM=$(gg -r --req="/func_test/update-data/key=\$i/value=d_\$i" --service --remote="127.0.0.1:2301")
...
for i in {1..1000}; do
...
RES=$(eval "$COMM")
...
echo "Result is $RES"
done
In this example, the code with "$i" variable is created, and then evaluated in a bash loop of 1000
iterations, with each execution of your service using dynamic run-time input parameter "$i", but
without executing "gg -r" 1000 times.
• -u Read stdin (standard input) and substitute any environment variables in the form of ${<var
name>} with their values, and output to stdout (stdout). This is useful in processing configuration
files that do not have parameter values hardcoded, but rather take them from the environment.
• -m Add Golf syntax and keyword highlighting rules for files with .golf extension to Vim editor for
the currently logged on user. Note that you must have Vim installed; vi alone will not work.
• --man Display list of all man pages for Golf, along with the section that each belongs to (i.e.
"string", "web", "program-flow" etc).
• -h Display help.
EXAMPLES
• Make application (-q), use three databases (--db) named mdb (MariaDB database), pdb (PostgreSQL)
and sdb (SQLite), produce debugging information (--debug), produce tracing information (--trace):
gg -q --db="mariadb:mdb postgres:pdb sqlite:sdb" --debug --trace
• make application, use MariaDB database db (--db), specify linker and C compilation flags, specify
maximum upload size of about 18M:
gg -q --db="mariadb:db" --lflag "-Wl,-z,defs" --cflag "-DXYZ123" --maxupload 18000000
• Make application that doesn't use any databases:
gg -q
SEE ALSO
Golf compiler and utility
gg See all documentation
$DATE $VERSION GOLF(2gg)