go-winres

A simple command line tool for embedding usual resources in Windows executables built with Go:

A manifest
An application icon
Version information (the Details tab in file properties)
Other icons and cursors

You might want to directly use winres as a library too: github.com/tc-hib/winres

Installation

To install the go-winres command, run:

go install github.com/tc-hib/go-winres@latest

Usage

Please type go-winres help to get a list of commands and options.

Typical usage would be:

Run go-winres init to create a winres directory
Modify the contents of winres.json
Before go build, run go-winres make

go-winres make creates files named rsrc_windows_*.syso that go build automatically embeds in the executable.

The suffix _windows_amd64 is very important. Thanks to it, go build knows it should not include that object in a Linux or 386 build.

Automatic version from git

The --file-version and --product-version flags can take a special value: git-tag. This will retrieve the current tag with git describe --tags and add it to the file properties of the executable.

Using `go generate`

You can use a //go:generate comment as well:

//go:generate go-winres make --product-version=git-tag

Subcommands

There are other subcommands:

go-winres simply is a simpler make that does not rely on a json file.
go-winres extract extracts resources from an exe file or a dll.
go-winres patch replaces resources directly in an exe file or a dll. For example, to enhance a 7z self extracting archive, you may change its icon, and add a manifest to make it look better on high DPI screens.

JSON format

The JSON file follows this hierarchy:

Resource type (e.g. "RT_GROUP_ICON" or "#42" or "MY_TYPE")
- Resource name (e.g. "MY_ICON" or "#1")
  - Language ID (e.g. "0409" for en-US)
    - Actual resource: a filename or a json structure

Standard resource types can be found there. But please never use RT_ICON or RT_CURSOR. Use RT_GROUP_ICON and RT_GROUP_CURSOR instead.

Icon JSON

{
  "RT_GROUP_ICON": {
    "APP": {
      "0000": [
        "icon_64.png",
        "icon_48.png",
        "icon_32.png",
        "icon_16.png"
      ]
    },
    "OTHER": {
      "0000": "icon.png"
    },
    "#42": {
      "0409": "icon_EN.ico",
      "040C": "icon_FR.ico"
    }
  }
}

This example contains 3 icons:

"APP"
"OTHER"
42

Windows Explorer will display "APP" because it is the first one. Icons are sorted by name in case sensitive ascending order, then by ID.

42 is an ID, not a name, this is why it comes last.

"APP" is made of 4 png files.
"OTHER" will be generated from one png file. It will be resized to 256x256, 64x64, 48x48, 32x32, and 16x16.
42 is a native icon, it probably already contains several images.

Finally, 42 will display a different icon for french users.

"0409" means en-US, which is the default.
"040C" means fr-FR.

You can find other language IDs there.

Cursor JSON

{
  "RT_GROUP_CURSOR": {
    "ARROW": {
      "0000": [
        {
          "image": "arrow_32.png",
          "x": 28,
          "y": 4
        },
        {
          "image": "arrow_48.png",
          "x": 40,
          "y": 6
        }
      ]
    },
    "MOVE": {
      "0409": "move_EN.cur",
      "040C": "move_FR.cur"
    },
    "#1": {
      "0000": {
        "image": "cross.png",
        "x": 16,
        "y": 16
      }
    }
  }
}

This example contains 3 cursors:

"ARROW" contains two images (one for higher DPI). It is a json array.
"MOVE" uses cur files directly. It is different in French. It is a string.
1 contains one image. It is an object.

When a cursor is made with a png file, you have to provide the coordinates of the "hot spot", that is, the pixel that clicks.

Manifest

The manifest should be defined as resource 1 with language 0409.

As a JSON object

{
  "RT_MANIFEST": {
    "#1": {
      "0409": {
        "identity": {
          "name": "",
          "version": ""
        },
        "description": "",
        "minimum-os": "win7",
        "execution-level": "as invoker",
        "ui-access": false,
        "auto-elevate": false,
        "dpi-awareness": "system",
        "disable-theming": false,
        "disable-window-filtering": false,
        "high-resolution-scrolling-aware": false,
        "ultra-high-resolution-scrolling-aware": false,
        "long-path-aware": false,
        "printer-driver-isolation": false,
        "gdi-scaling": false,
        "segment-heap": false,
        "use-common-controls-v6": false
      }
    }
  }
}

All boolean values default to false.

It is recommended to omit identity if your program is a plain application, not meant to be a side-by-side dependency.

Values for `"execution-level"`:

"" (default)
"highest": elevates to the highest level available to the current user
"administrator": require the user to be an administrator and elevate to this level

Values for `"minimum-os"`:

"vista"
"win7" (default)
"win8"
"win8.1"
"win10"

Values for `"dpi-awareness"`:

"unaware"
"system" (default)
"per monitor"
"per monitor v2" (recommended)

As an XML file

{
  "RT_MANIFEST": {
    "#1": {
      "0409": "my_manifest.xml"
    }
  }
}

VersionInfo JSON

Here is an example JSON file containing every standard info field, a French translation, and every possible flag. "0409" and "040C" are language code identifiers (LCID) for en-US and fr-FR respectively.

{
  "RT_VERSION": {
    "#1": {
      "0000": {
        "fixed": {
          "file_version": "1.2.3.4",
          "product_version": "1.2.3.42",
          "flags": "Debug,Prerelease,Patched,PrivateBuild,SpecialBuild",
          "timestamp": "2020-12-18T23:00:00+01:00"
        },
        "info": {
          "0409": {
            "Comments": "Comments",
            "CompanyName": "Company",
            "FileDescription": "A description",
            "FileVersion": "1.2.3.4",
            "InternalName": "",
            "LegalCopyright": "© You",
            "LegalTrademarks": "",
            "OriginalFilename": "X.EXE",
            "PrivateBuild": "",
            "ProductName": "Product",
            "ProductVersion": "1.2.3.42 beta",
            "SpecialBuild": ""
          },
          "040C": {
            "Comments": "Commentaire",
            "CompanyName": "Compagnie",
            "FileDescription": "Une description",
            "FileVersion": "1.2.3.4",
            "InternalName": "",
            "LegalCopyright": "© Vous",
            "LegalTrademarks": "",
            "OriginalFilename": "X.EXE",
            "PrivateBuild": "",
            "ProductName": "Produit",
            "ProductVersion": "1.2.3.42 bêta",
            "SpecialBuild": ""
          }
        }
      }
    }
  }
}

Alternatives

This project is similar to akavel/rsrc and josephspurrier/goversioninfo.

Additional features are:

Multilingual resources
Multilingual VersionInfo that works in Windows Explorer
Explicitly named resources, by ID or by string (so you can use them in runtime)
Extracting resources from exe or dll files
Replacing resources in exe or dll files
Simplified VersionInfo definition
Simplified manifest definition
Support for custom information in VersionInfo
Making an icon or a cursor from a PNG file
Embedding custom resources

It might be closer to Microsoft specifications too.

Limitations

go-winres is not a real resource compiler, which means it won't help you embed these UI templates:

ACCELERATORS
DIALOGEX
MENUEX
POPUP

If you ever need them, you can use one of those tools instead:

rc.exe and cvtres.exe from Visual Studio
windres from GNU Binary Utilities
llvm-rc and llvm-cvtres from LLVM tools

See Resource Compiler for more information.

Thanks

Many thanks to akavel for his help.

This project uses these very helpful libs:

nfnt/resize - pure Go image resizing
urfave/cli - makes building a CLI easier

tc-hib/go-winres