halimath / include

A go:generate generator to include files in go sources

include

---

This module is not maintained anymore. Please use https://pkg.go.dev/embed instead.

include is a generator which includes file content into string or []byte variables of go modules. This generator is inspired by the Rust macro include_str which is used to include a file as a rust variable.

Use this generator if you want to build a single binary that includes static assets such as html, scripts, css or any other data as part of the produced binary.

Usage

Install the generator:

$ go install github.com/halimath/include/cmd/include@latest

Add the library as a dependency:

$ go get github.com/halimath/include

Now, create one or more source files that contain package variable declarations which are initialized with a call to either include.String or include.Bytes.

import "github.com/halimath/include"

var html = include.String("./html/index.html")

Only package level variable declarations are processed.

Add a go build tag comment for include so that this file will not be included in a regular build. The generated go file will cary the inverse build tag.

//go:build include

You can customize the build tag with the --build-tag cli option.

Add a go:generate comment to instruct go generate how to generate a version of this file with all calls to the above functions replaced with actual file content:

//go:generate include --out file_gen.go $GOFILE

Run

$ go generate <file>

to run the generator.

Generator CLI options

The following options are supported by the generator:

Option	Default Value	Description
out	-	Name of the output file to write to. If not specified the generated source will be written to stdout.
buildtag	include	Build tag to deactivate in generate source.

License

Copyright 2021 Alexander Metzner.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.