astibundler

README

This package provides a way to bundle an astilectron app using the bootstrap.

Check out the demo to see a working example.

Installation

Run the following command:

go get -u github.com/asticode/go-astilectron-bundler/...

Build the binary

Run the following command:

go install github.com/asticode/go-astilectron-bundler/astilectron-bundler

Configuration

astilectron-bundler uses a configuration file to know what it's supposed to do.

Basic configuration

Here's the basic configuration you'll usually need:

{
  "app_name": "Test",
  "icon_path_darwin": "path/to/icon.icns",
  "icon_path_linux": "path/to/icon.png",
  "icon_path_windows": "path/to/icon.ico"
}

It will process the project located in the current directory and bundle it in the output dir for your os/arch.

Bundle for specific Astilectron and/or Electron versions

The following customization can be made to bundler.json

• version_electron - version of electron, defaults to the value specified in the go-astilectron version you're using
• version_astilectron - version of astilectron, defaults to the value specified in the go-astilectron version you're using

Bundle for other environments

You can bundle your project for multiple environments with the environments key:

{
  "environments": [
    {"arch": "amd64", "os": "darwin"},
    {"arch": "amd64", "os": "linux"},
    {
      "arch": "amd64",
      "os": "windows",
      "env": {
        "CC": "x86_64-w64-mingw32-gcc",
        "CXX": "x86_64-w64-mingw32-g++",
        "CGO_ENABLED": "1"
      }
    }
  ]
}

For each environment you can specify environment variables with the env key.

Adapt resources

You can execute custom actions on your resources before binding them to the binary such as uglifying the .js files with the resources_adapters key:

{
  "resources_adapters": [
    {
      "args": ["myfile.js", "mynewfile.js"],
      "name": "mv"
    },
    {
      "args": ["-flag", "value", "mynewfile.js"],
      "name": "myawesomebinary"
    }
  ]
}

All paths must be relative to the resources folder except if you provide a dir option (a path relative to the resources folder) in which case it will be relative to that path.

Build flags

You can pass arbitrary build flags into the build command with the build_flags key:

{
  "build_flags": {
    "gcflags": "\"all=-N -l\""
  }
}

Custom paths

You can set the following paths:

• input_path: path to your project. defaults to the current directory
• go_binary_path: path to the go binary. defaults to "go"
• output_path: path to the dir where you'll find the bundle results. defaults to current directory/output
• resources_path: path where the resources dir is and will be written. path must be relative to the input_path. defaults to "resources"
• vendor_dir_path: path where the vendor dir will be written. path must be relative to the output_path
• working_directory_path: path to the dir where the bundler runs its operations such as provisioning the vendor files or binding data to the binary

Adapt the bind configuration

You can use the bind attribute to alter the bind configuration like so:

{
  "bind": {
    "output_path": "path/to/bind/output/path",
    "package": "mypkg"
  }
}

• output_path: path to the directory where you want bind files to be created. defaults to the current working directory
• package: the package name to use for the bind files. defaults to "main"

When you specify an output_path, the package will probably need to be set.

Info.plist generation from the bundler configuration file property

You can add custom Info.plist configuration to the bundler.json:

{
  "app_name": "Best App",
  "icon_path_darwin": "resources/icon.icns",
  "info_plist": {
    "CFBundlePackageType": "APPL",
    "CFBundleInfoDictionaryVersion": "6.0",
    "CFBundleIconFile": "icon.icns",
    "CFBundleDisplayName": "Best App",
    "CFBundleExecutable": "app_binary",
    "CFBundleIdentifier": "com.company.BestApp",
    "LSUIElement": "NO",
    "LSMinimumSystemVersion": "10.11",
    "NSHighResolutionCapable": true,
    "NSAppTransportSecurity": {
      "NSAllowsArbitraryLoads": true
    }
  }
}

Usage

If astilectron-bundler has been installed properly (and the $GOPATH is in your $PATH), run the following command:

astilectron-bundler -c <path to your configuration file>

or if your working directory is your project directory and your bundler configuration has the proper name (bundler.json)

astilectron-bundler

Output

For each environment you specify in your configuration file, astilectron-bundler will create a folder <output_path you specified in the configuration file>/<os>-<arch> that will contain the proper files.

Ldflags

astilectron-bundler uses ldflags when building the project. It means if you add one of the following variables as global exported variables in your project, they will have the following value:

• AppName: filled with the configuration app name
• BuiltAt: filled with the date the build has been done at
• VersionAstilectron: filled with the version of Astilectron being bundled/used
• VersionElectron: filled the version of Electron being bundled/used

You can use the following to alter the Ldflags behavior:

{
  "ldflags_package": "some/path/to/pkg"
}

• ldflags_package: which local package these variables exist in. defaults to bind's package value (for backwards compatibility)

If you need to add more flags yourself, like for a version number, add something like this to your astilectron-bundler command: -ldflags X:main.Version=xyzzy.

If you need to add multiple flags you can pass -ldflags multiple times, with multiple values split on commas, like this:

-ldflags X:main.Version=xyzzy,main.CommitCount=100 -ldflags race

That would set two variables and enable the race detection.

(in either case, make sure to substitute main with the package where your Version/CommitCount/etc. variables exist)

Commands

Only bind data: bd

Use this command if you want to skip most of the bundling process and only bind data/generate the bind.go file (useful when you want to test your app running go run *.go):

astilectron-bundler bd -c <path to your configuration file>

Clear the cache: cc

The bundler stores downloaded files in a cache to avoid downloading them over and over again. That cache may be corrupted. In that case, use this command to clear the cache:

astilectron-bundler cc

Frequent problems

"xxx architecture of input file `xxx' is incompatible with xxx output"

When building for linux you may face an error looking like this:

FATA[0009] bundling failed: bundling for environment linux/amd64 failed: building failed: # github.com/asticode/go-astilectron-demo
/usr/local/go/pkg/tool/linux_amd64/link: running gcc failed: exit status 1
/usr/bin/ld: i386 architecture of input file `/tmp/go-link-275377070/000000.o' is incompatible with i386:x86-64 output
collect2: error: ld returned 1 exit status

Thanks to this comment, you need to add the ldflags key to your bundler.json with the value {"linkmode":["internal"]}.

Documentation

Index

• func NewProvisioner(disembedFunc func(string) ([]byte, error), l astikit.StdLogger) astilectron.Provisioner
• type Bundler
  • func New(c *Configuration, l astikit.StdLogger) (b *Bundler, err error)
  • func (b *Bundler) BindData(os, arch string) (err error)
  • func (b *Bundler) Bundle() (err error)
  • func (b *Bundler) ClearCache() (err error)
  • func (b *Bundler) HandleSignals()
  • func (b *Bundler) Stop()
• type Configuration
• type ConfigurationBind
• type ConfigurationEnvironment
• type ConfigurationResourcesAdapter
• type LDFlags
  • func (l LDFlags) Merge(r LDFlags)
  • func (l LDFlags) String() string

Functions

func NewProvisioner

func NewProvisioner(disembedFunc func(string) ([]byte, error), l astikit.StdLogger) astilectron.Provisioner

NewProvisioner builds the proper disembedder provisioner

Types

type Bundler

type Bundler struct {
	// contains filtered or unexported fields
}

Bundler represents an object capable of bundling an Astilectron app

func New

func New(c *Configuration, l astikit.StdLogger) (b *Bundler, err error)

New builds a new bundler based on a configuration

func (*Bundler) BindData

func (b *Bundler) BindData(os, arch string) (err error)

BindData binds the data

func (*Bundler) Bundle

func (b *Bundler) Bundle() (err error)

Bundle bundles an astilectron app based on a configuration

func (*Bundler) ClearCache

func (b *Bundler) ClearCache() (err error)

ClearCache clears the bundler cache

func (*Bundler) HandleSignals

func (b *Bundler) HandleSignals()

HandleSignals handles signals

func (*Bundler) Stop

func (b *Bundler) Stop()

Stop stops the bundler

type Configuration

type Configuration struct {
	// The app name as it should be displayed everywhere
	// It's also set as an ldflag and therefore accessible in a global var package_name.AppName
	AppName string `json:"app_name"`

	// The bind configuration
	Bind ConfigurationBind `json:"bind"`

	// Whether the app is a darwin agent app
	DarwinAgentApp bool `json:"darwin_agent_app"`

	// List of environments the bundling should be done upon.
	// An environment is a combination of OS and ARCH
	Environments []ConfigurationEnvironment `json:"environments"`

	// The path of the go binary
	// Defaults to "go"
	GoBinaryPath string `json:"go_binary_path"`

	// Paths to icons
	IconPathDarwin  string `json:"icon_path_darwin"` // .icns
	IconPathLinux   string `json:"icon_path_linux"`
	IconPathWindows string `json:"icon_path_windows"` // .ico

	// Info.plist property list
	InfoPlist map[string]interface{} `json:"info_plist"`

	// The path of the project.
	// Defaults to the current directory
	InputPath string `json:"input_path"`

	// Build flags to pass into go build
	BuildFlags map[string]string `json:"build_flags"`

	// LDFlags to pass through to go build
	LDFlags LDFlags `json:"ldflags"`

	// The path used for the LD Flags
	// Defaults to the `Bind.Package` value
	LDFlagsPackage string `json:"ldflags_package"`

	// The path to application manifest file (WINDOWS ONLY)
	ManifestPath string `json:"manifest_path"`

	// The path where the files will be written
	// Defaults to "output"
	OutputPath string `json:"output_path"`

	// List of commands executed on resources
	// Paths inside commands must be relative to the resources folder
	ResourcesAdapters []ConfigurationResourcesAdapter `json:"resources_adapters"`

	// The path where the resources are/will be created
	// This path must be relative to the input path
	// Defaults to "resources"
	ResourcesPath string `json:"resources_path"`

	// Show Windows console
	ShowWindowsConsole bool `json:"show_windows_console"`

	// The path where the vendor directory will be created
	// This path must be relative to the output path
	// Defaults to a temp directory
	VendorDirPath string `json:"vendor_dir_path"`

	// Version of Astilectron install
	VersionAstilectron string `json:"version_astilectron"`

	// Version of Electron install
	VersionElectron string `json:"version_electron"`

	// The path to the working directory.
	// Defaults to a temp directory
	WorkingDirectoryPath string `json:"working_directory_path"`

	//!\\ DEBUG ONLY
	AstilectronPath string `json:"astilectron_path"` // when making changes to astilectron
}

Configuration represents the bundle configuration

type ConfigurationBind

type ConfigurationBind struct {
	// The path where the file will be written
	// Defaults to the input path
	OutputPath string `json:"output_path"`

	// The package of the generated file
	// Defaults to "main"
	Package string `json:"package"`
}

type ConfigurationEnvironment

type ConfigurationEnvironment struct {
	Arch                 string            `json:"arch"`
	EnvironmentVariables map[string]string `json:"env"`
	OS                   string            `json:"os"`
}

ConfigurationEnvironment represents the bundle configuration environment

type ConfigurationResourcesAdapter

type ConfigurationResourcesAdapter struct {
	Args []string `json:"args"`
	Dir  string   `json:"dir"`
	Name string   `json:"name"`
}

type LDFlags

type LDFlags map[string][]string

LDFlags represents ldflags

func (LDFlags) Merge

func (l LDFlags) Merge(r LDFlags)

Merge merges ldflags

func (LDFlags) String

func (l LDFlags) String() string

String returns the ldflags as a string