Gg

Purpose: Gliimly general purpose utility: build, test, run, miscellaneous (pronounced "gigi").

gg <options>

Command-line options

-q Build Gliimly 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 Gliimly source file (.gliim 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 Gliimly'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-Gliimly 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 an application, emit a maxium of <max errors> diagnostic messages. The default is 5.
- --debug
  Generate debugging information when compiling your application. Debugging information is required to produce a backtrace file with the stack that contains source code line numbers, in order to pinpoint the exact location where report-error statement was used, or where the application crashed. It is also needed to use gdb for debugging purposes. Note that stack information is produced only when Gliimly is built in debugging mode (see "DI=1" option when installing Gliimly).
- --c-lines
  Skip generating line information when compiling .gliim files. By default line information is included, which allows errors to be reported with line numbers in .gliim 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.
- --optimize-memory
  Use memory-optimizing garbage collection, which counts memory references and frees memory as soon as possible. Default is without memory optimization, which frees memory at the end of the request. Do not use this option unless your system is seriously starved for memory because it imposes a performance penatly (in some tests 15-25%).
- --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 compatibile, you can use either one depending on your needs.
- --plain-diag
  Do not use color-coded and more detailed Gliimly diagnostic output. While rare, you may need this option in cases when there may be a Gliimly 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 Gliimly 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 Gliimly 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 Gliimly 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 gliimdoc.html file.
-l
Show library directory - Gliimly'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 Gliimly 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
```
When "--exec" is not used, the output may look like this:
```
export CONTENT_TYPE=
export CONTENT_LENGTH=
export GG_SILENT_HEADER=no
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). 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.

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
```
-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 Gliimly syntax and keyword highlighting rules for files with .gliim extension to Vim editor for the currently logged on user. Note that you must have Vim installed; vi alone will not work.
-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
```