GOLF(2gg)

📦 version 601.4.41, in ubuntu questing

okay so you just opened the GOLF(2gg) manual page, and the section is Development, and bestie it is LONG, so this is part 1 of 2 — grab a snack 🍓 and let's lock in.

✨ NAME ✨

gg — (golf-compiler-and-utility)

🎯 PURPOSE 🎯

Golf general purpose utility: build, test, run, miscellaneous. and it's pronounced "gigi", no cap 💅

📜 SYNTAX 📜

gg <options>

🌸 DESCRIPTION 🌸

💫 COMMAND-LINE OPTIONS 💫

  • -k <app name> — creates a Golf application called <app name> with the default settings. (if you want non-default settings, go look at mgrg and its -i option, that's the one for that.) and what even are the defaults, you ask? well: your app gets owned by the Operating System user who's currently logged on (peep the -u option in mgrg for that), and the Unix socket that connects to your application server isn't restricted by any group at all (that's the -r option in mgrg). you must have sudo privilege to create an application — and this is literally the only option that needs it, iconic. if the application already exists, this option does absolutely nothing, so don't stress. oh and you can combine it with -q to create and build an application in one single step, chef's kiss 🔥
  • -q — builds a Golf application from the source code sitting in the current directory. heads up: mgrg has to run first in this directory with the -i option to actually create the application. you need at least one Golf source file (a .golf file), and each one of those files implements a single request handler. all application source files have to live in a flat directory — but don't worry, each request handler can still handle any hierarchical path you want, so your API can be fully hierarchical. slay.

the following options can be used when building an application:

  • --db="<database vendor>:<db config file> ..." — tells Golf which databases your application uses. every element of the list is <database vendor> (which has to be 'mariadb', 'postgres' or 'sqlite'), then a colon (:), then <db config file> — and that config file is what you use to refer to a database in statements like run-query. each <database vendor>:<db config file> pair is separated by a space, and you can list any number of databases for your app. a file in the current directory with the name <db config file> must exist and must contain the connection parameters for database access — it gets copied into Golf's database configuration directory (see directories). for more on what goes inside that file, check database-config-file. 🗄️
  • --lflag=<linker flags> — if you wanna add any extra linker flags (like, say, any non-Golf libraries), put them in here, quoted. 🔗
  • --cflag=<C flags> — if you wanna add any extra C compiler (gcc) flags, drop them here, quoted.
  • --trace — if you pass this, tracing information code gets generated. (without it, tracing isn't available at all and the trace-run statement is just ignored, rip.) and lowkey important: tracing only works when debugging mode is enabled, so you have to use --debug as well. both or neither.
  • --path=<application path> — lets you set the application path for your request URLs. it's the leading path of a URL, before the request name and any parameters. if it's empty, the default is the application name with a forward slash in front of it:
/<app name>
  • --maxupload=<max upload size> — sets the maximum upload size for a file, in bytes. the default is approximately 25MB.
  • --max-errors=<max errors> — while building 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 though that the Golf precompiler stops after the first error in most cases, and this setting does not apply to it.
  • --debug — debugging information is always included in Golf executables, even when it lives in separate .dbg (or .debug) files. so what's the --debug flag even for? it's only necessary if you're using tracing (see trace-run), plus it's how you include additional run-time checks. > ⚠️ do not use --debug unless you're a Golf upstream developer or maintainer, because it may significantly lower the run-time performance. you've been warned bestie 🙈
  • --c-lines — skips generating line information when compiling .golf files. by default line info is included, which is what lets errors get reported with line numbers in your .golf files. if you'd rather only use generated C code line numbers, use this option. just know the output will omit certain color-coded and other details that are normally there without it. 🎨
  • --public — flips the default behavior of request handler safety, so that request handlers without a "public" or "private" clause are "public" by default. see begin-handler for the full tea.
  • --single-file — normally a request handler is written in a source file whose path matches fully or partially that of the request, and such a file can hold any number of matching request handlers (see request). but if you use --single-file, then every request has to be in its own file whose path matches the request path fully, and no other request can be implemented in that 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 file "newreq.golf" inside subdirectory "other" in the source directory. one file, one request, periodt.
  • --exclude-dir — by default, all .golf files get picked up for compilation, including ones in all subdirectories no matter how many levels deep they go. if you use --exclude-dir, then you can specify any number of subdirectories to exclude, separated by commas.
  • --ignore-warn — doesn't display any warnings during compilation of a Golf application. silence is golden ✨
  • --parallel=<threads> — uses <threads> number of threads to compile the application. by default the number of threads equals the number of CPUs (including virtual ones), which lets each CPU compile one source file at a time — and that's usually the fastest way. you can serialize the compilation with --parallel=1, or set <threads> to any number between 1 and three times the number of CPUs to hit your own performance and CPU utilization goals. go off, multitasking queen 👑
  • --posix-regex — uses the ERE (Extended Regular Expression) POSIX regex library built into Linux instead of the default PCRE2, see match-regex. the two are largely compatible, so you can use either one depending on your needs.
  • --plain-diag — don't use color-coded and more detailed Golf diagnostic output. it's rare, but you might need this in cases where there's a Golf or underlying compiler bug, or for some other reason. 🐛
  • -c, --clean — cleans all object and other intermediate files, so that the next 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 — displays both include and linking flags for an application that uses Client-API to connect to Golf service. these flags are for the C compiler (gcc). if --include is used in addition, then only include flags get displayed. if --link is used in addition, then only linking flags get displayed. use this to automate building of client applications with tools like Makefile. 🤖
  • -v — displays the Golf version as well as the Operating System version. ⭐
  • -s — traces the execution of the gg utility and displays all the steps in making your application. 🔍
  • -e <num of errors> — shows the last <num of errors> from the backtrace file, which receives the error message and stack trace whenever a program crashes or report-error is issued. it also displays the path to the backtrace file that contains the stack details. 😭
  • -t <num of trace files> — shows 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. it also displays the path to the backtrace file which contains the stack details.
  • -o — shows the documentation directory — the web page documentation lives here in the form of a golfdoc.html file. 📚
  • -g — shows the Golf root directory (i.e. where Golf is installed, see directories).
  • -l — shows the library directory — Golf's libraries and the v1 code processor are located there.
  • -r — run a command-line program, or make a service request, or display bash code to do the same for use in scripts. here's the whole shape of it:
-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 ]

if you're not in the application's source code directory, then you must specify the --app option to supply the application path (typically "/<application name>", see request). you can use the --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 it's not specified, the default method is "GET".

if --service is not used, then the command-line program will execute, and you can specify program arguments with the --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 the -a option in mgrg.

If --service is on, then the application server gets pinged to run a service 💫 — and in that case, if --remote isn't specified, it's a local Unix socket doing the contacting; otherwise the server:port you put in --remote is the IP/name and port of the server to call, separated by a colon (:). For a local Unix socket, the socket path defaults to /var/lib/gg/<app name>/sock/sock, where /<app name> comes from the last path segment in the --app option, or — if you didn't set that — it's derived from the name of a Golf application built in the current directory; otherwise the socket path is whatever --socket says. 🧚

By default, the output is gonna have the HTTP headers, always. If you do NOT want those showing up, use --silent-header. 🙈

If --content is used, then file <input file> is either piped to the standard input of a command-line program (when --service is not used), or sent as a content to the application server (when --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, but bestie, for maximum performance, skip the --exec option so it displays direct bash code that you can copy and paste to use in production. That 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. Obsessed, honestly. 👑

  • -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

That's the whole thing, bestie — this page is from the $DATE era and it's rocking version $VERSION 💖 no cap, go build something iconic with it ✨👑

📦 where this page comes from