\input texinfo
@comment %**start of header
@setfilename godcc.info
@include version.texi
@settitle godcc manual
@afourpaper
@defcodeindex pv
@comment %**end of header

@copying
This manual describes godcc (version @value{VERSION},
@value{UPDATED}).

Copyright @copyright{} 2026 Jose E. Marchesi.

@quotation
You can redistribute it and/or modify this manual under the terms of
the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any
later version.
@end quotation
@end copying

@dircategory Network applications
@direntry
* godcc: (godcc).  A command-line interface to Compiler Explorer.
@end direntry

@titlepage
@title godcc Manual
@subtitle for version @value{VERSION}, @value{UPDATED}
@author by Jose E. Marchesi
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top godcc Manual

@insertcopying
@end ifnottex

@command{godcc} is a full-fledged command-line interface to Compiler
Explorer instances such as @url{https://godbolt.org}.

@menu
* Building godcc::          Building from sources.
* Configuration::           Getting godcc ready to work.
* Dealing with HTTPS::      The insecurity of modern hackers.
* Getting listings::        Lists of compilers, languages, @i{etc}.
* Compiling::               Compiling source files.
* Formatting::              Formatting source code.

* GNU General Public License::
@end menu

@node Building godcc
@chapter Building godcc

@menu
* Building an Algol 68 toolchain::
* Building godcc from sources::
@end menu

@node Building an Algol 68 toolchain
@section Building an Algol 68 toolchain

godcc is written in Algol 68.  The GNU Algol 68 compiler is still
under development and will be released as part of GCC 16 at some point
during Spring 2026.

Until then, to build godcc you will need to build your own Algol 68
toolchain.  But don't worry, it is very easy!

First build and install ga68 from the latest GCC trunk:

@example
$ git clone https://gcc.gnu.org/git/gcc.git
$ cd gcc
$ ./contrib/download_prerequisites
$ mkdir build && cd build/
$ ../configure --prefix=$HOME/root-algol68 --enable-languages=algol68
$ make && make pdf && make html
$ make install
@end example

Automake has Algol 68 support starting in version 1.18.  You can build
that release easily by:

@example
$ wget https://ftp.gnu.org/gnu/automake/automake-1.18.tar.gz
$ tar xzvf automake-1.18.tar.gz
$ cd automake
$ mkdir build && cd build/
$ ../configure --prefix=$HOME/root-algol68
$ make && make install
@end example

Autoconf has Algol 68 support in its development (git) version, which
will eventually be released as Autoconf 2.73.  In the meanwhile you
can easily build the development version:

@example
$ git clone https://git.savannah.gnu.org/git/autoconf.git
$ cd autoconf
$ mkdir build && cd build/
$ ../configure --prefix=$HOME/root-algol68
$ make && make install
@end example

At this point you should have working tools in whatever prefix you
specified in `--prefix`.

@node Building godcc from sources
@section Building godcc from sources

Once you have the Algol 68 toolchain built in some reachable place,
you can build godcc simply like:

@example
$ cd godcc/
$ autoreconf
$ mkdir build && cd build/
$ ../configure && make -j && make install
@end example

It is possible to set the @code{A68FLAGS} environment variable to
specify extra compilation flags.

@node Configuration
@chapter Configuration

You configure godcc by setting a couple of environment variables:

@table @code
@item GODCC_CEHOST
The host where the instance of Compiler Explorer can be reached.  It
is a hostname.
@item GODCC_CEPORT
The port to connect to.
@end table

For example:

@example
$ export GODCC_CEHOST=mycompilerexplorer.com GODCC_PORT=80
@end example

See below about how to deal with https.  You will need that to get
godcc to talk to godbolt.org.

@node Dealing with HTTPS
@chapter Dealing with HTTPS

Due to the generalized nonsense of today's Internet, which prescribes
``security'' for absolute everything effectively achieving insecurity
for everyone, it is almost certain the Compiler Explorer instance you
want to access, such as godbolt.org, will require being accessed via
https.

In that case you will have to establish a tunnel that translates the
plain http that godcc talks into the https gibberish.  A way to do
that is using the stunnel program.  This is the recipe:

First create a @file{godbolt.stunnel} configuration file containing
this:

@example
sslVersion = all
foreground = yes
[remote]
client = yes
accept = 8888
connect = godbolt.org:443
@end example

Then run stunnel:

@example
# sudo stunnel godbolt.stunnel
@end example

Finally configure godcc to connect to localhost:8888:

@example
$ export GODCC_CEHOST=localhost GODCC_CEPORT=8888
@end example

@node Getting listings
@chapter Getting listing

The @command{list} subcommand provides information about languages,
compilers and formatters supported by the instance of Compiler
Explorer.

List of languages:

@example
$ godcc list languages
@end example

The `list compilers` subcommand will print a list of all the compilers
supported by the instance of Compiler Explorer:

@example
$ godcc list compilers
@end example

This may be a long list.  If you are interested in compilers for a
particular programming language, you can use:

@example
$ godcc list compilers -l zig
@end example

List of code formatting styles supported by Compiler Explorer:

@example
$ godcc list formats
@end example

@node Compiling
@chapter Compiling

The @command{compile} subcommand compiles some given source code in
Compiler Explorer into assembly language.  The synopsis is:

@example
godcc compile [-c COMPILER] [-o OUTFILE] [-- [COMPOPTS]] [SRCFILE]
@end example

An example is:

@example
$ godcc compile foo.c -c cbpfgtrunk
# Compilation provided by Compiler Explorer at https://godbolt.org/
foo:
        *(u32 *) (r10+-4) = r1
        r0 = *(u32 *)         if w0 s<= 0 goto .L2
        w0 += 1
        r0 s>>= 32
  .L2:
        exit
@end example

By default the source code is read from standard input and the
compiled assembly code is printed on the standard output.  This can be
changed using command-line options.

For example, to compile @file{foo.c} to assembly and put the result in
@file{foo.s}:

@example
$ godcc compile -c cbpfgtrunk foo.c -o foo.s
@end example

Options specified after @command{--} are sent as-is to the remote
compiler.  This is useful to change optimization levels, or library
links, or debug info options:

@example
$ godcc compile -c cbpfgtrunk foo.c -- -O2 -Wall
@end example

Having to specify the compiler to use at every invocation can be
annoying.  If godcc is invoked as `godcc-COMPILER`, the `COMPILER`
part is interpreted as the default compiler to use.  So for example,
if you often use godcc to compile C to BPF using GCC, you may want to
create a symlink:

@example
$ ln -s /usr/bin/godcc /usr/bin/godcc-cbpfgtrunk
$ godcc-cbpfgtrunk compile foo.c
@end example

@node Formatting
@chapter Formatting

The @command{format} subcommand provides access to format souce code
using Compiler Explorer.  The synopsis is:

@example
godcc format [-f FORMATTER] [-s STYLE] [SRCFILE]
@end example

An example is:

@example
$ godcc format foo.c -f clangformat -s Google foo.c
int foo(int i) @{
  if (i > 0) @{
      return i + 1;
  @} else @{
      return 0;
  @}
@}
@end example

By default the source code is read from standard input and the
formatted code is printed on the standard output.  This can be changed
using command-line options.

For example, to format foo.c to use Google style and put the result in
a file @file{foo-google.c}:

@example
$ godcc format -f clangformat -s Google foo.c -o foo-google.c
@end example

@include gpl_v3.texi

@bye
