gocc/README.md

# gocc

A high-performance cross compiler for Go

## Source code

You can find the source code here: [git.milar.in](https://git.milar.in/milarin/gocc)

## Installation

If you have Go installed, you can simply go install the program: `go install git.milar.in/milarin/gocc@latest`

There are pre-compiled executables for various platforms on the [repository](https://git.milar.in/milarin/gocc/releases).

## License

Distributed under the MIT License. See [LICENSE.md](https://git.milar.in/milarin/gocc/src/branch/main/LICENSE.md)

## Usage

### Basic syntax

`gocc [<arguments>] [<module>]`

### Arguments

Using `--help` shows a description for all available arguments:

```sh
$ gocc --help
Usage of ./gocc:
  -arch string
    	comma-separated list of architectures to compile for (empty for all)
  -c	dont compress any executables
  -f string
    	go template for filenames (default "{{.Name}}-{{.OS}}-{{.Arch}}{{.Ext}}")
  -findconfig
    	print config file path and exit
  -ignoreconfig
    	dont read any config file
  -o string
    	output directory (default "output")
  -os string
    	comma-separated list of operating systems to compile for (empty for all)
  -s	silent mode (no output)
  -saveconfig
    	save config file with current configuration and exit
  -t int
    	amount of threads (0 = infinite) (default 16)
```

#### Providing a Go module

By default, `gocc` compiles the module in the current working directory.
You can provide a custom module path after all other arguments.

For example:  `gocc -t 4 -ignoreconfig path/to/go/module`

#### Choosing Operating systems

You can decide, for which operating systems `gocc` should compile for via `-os`.
Provide the operating systems as a comma-separated list.

For example: `gocc -os "windows,linux"`

For a list of supported operating systems, run `go tool dist list`

#### Choosing architectures

Analogous to operating systems, you can provide architectures via `-arch`.

For example: `gocc -arch "amd64,386"`

For a list of supported architectures, run `go tool dist list`

#### Output path

By default, `gocc` will save all executables in the folder `output` in the current working directory.
You can set a custom path via `-o`

#### Disable compression

All executables will be compressed automatically if `upx` is found in `$PATH`.
This behavior can be disabled via `-c`.

#### Multithreaded compilation

Compilation is multi-threaded by default. You can set the amount of concurrent compilations via `-t <threads>`.
If no thread count is provided, the amount of CPU cores will be used.
(the default value shown with `--help` is always the amount of CPU cores on the current machine)

A thread count of `0` runs all tasks at the same time. This could lead to lags and freezes on your machine!

If you want to disable multi-threaded compilation, just use `-t 1`

#### Silent mode

Providing `-s` enables silent mode. When enabled, `gocc` will never show any output.
A non-zero exit code indicates errors.

#### Customize default behavior

You can change the default values of all other arguments with `-saveconfig`.
Simply provide all arguments as you like and save your config in a json file.
Next time `gocc` is run, the config file will be loaded and your preferred command line arguments will be automatically set.

You can still manually overwrite arguments by providing them directly.
But that will not always result in the default behavior if no config file exists.
For these cases you can use `-ignoreconfig`.

If you want to get rid of your config file or you want to edit it manually, you can find it by running `gocc -findconfig`

**No compilation will be done if `-saveconfig` is provided!**

**`-findconfig` does not work with silent mode (`-s`)!**

**Always use `-ignoreconfig` in scripts! You don't know what config file your user might have!**

#### Change executable filename pattern

You can provide a custom filename pattern for the compiled executables via `-f`.
The value feeded into `-f` is a Go template.
See the official Go docs for [Go templates](https://pkg.go.dev/text/template) for more information.

The following values are available inside the template:
- `Name`: the module name
- `OS`: the operating system
- `Arch`: the architecture
- `Ext`: the file extension (for windows: `.exe`, for any other operating system: ``)

The default value is `{{.Name}}-{{.OS}}-{{.Arch}}{{.Ext}}`