{"id":14008140,"url":"https://github.com/lu4p/binclude","last_synced_at":"2025-07-24T03:32:00.646Z","repository":{"id":45008994,"uuid":"272128845","full_name":"lu4p/binclude","owner":"lu4p","description":"Include files in your binary the easy way","archived":true,"fork":false,"pushed_at":"2021-02-17T00:23:09.000Z","size":8459,"stargazers_count":279,"open_issues_count":1,"forks_count":9,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-08-10T11:02:40.008Z","etag":null,"topics":["binary-data","golang","resource-embedding","static-files"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lu4p.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"lu4p"}},"created_at":"2020-06-14T03:53:54.000Z","updated_at":"2024-07-09T09:48:12.000Z","dependencies_parsed_at":"2022-08-25T13:41:40.156Z","dependency_job_id":null,"html_url":"https://github.com/lu4p/binclude","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lu4p%2Fbinclude","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lu4p%2Fbinclude/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lu4p%2Fbinclude/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lu4p%2Fbinclude/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lu4p","download_url":"https://codeload.github.com/lu4p/binclude/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227410470,"owners_count":17774756,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binary-data","golang","resource-embedding","static-files"],"created_at":"2024-08-10T11:01:17.013Z","updated_at":"2024-11-30T19:30:46.314Z","avatar_url":"https://github.com/lu4p.png","language":"Go","funding_links":["https://github.com/sponsors/lu4p"],"categories":["Go"],"sub_categories":[],"readme":"*New Projects should use the official [embed](https://golang.org/pkg/embed/) package instead, which was added in go 1.16.*\n\n# binclude\n\n[![PkgGoDev](https://pkg.go.dev/badge/github.com/lu4p/binclude)](https://pkg.go.dev/github.com/lu4p/binclude)\n[![Test](https://github.com/lu4p/binclude/workflows/Test/badge.svg)](https://github.com/lu4p/binclude/actions?query=workflow%3ATest)\n[![Go Report Card](https://goreportcard.com/badge/github.com/lu4p/binclude)](https://goreportcard.com/report/github.com/lu4p/binclude)\n[![codecov](https://codecov.io/gh/lu4p/binclude/branch/master/graph/badge.svg)](https://codecov.io/gh/lu4p/binclude)\n\nbinclude is a tool for including static files into Go binaries.\n- focuses on ease of use\n- the bincluded files add no more than the filesize to the binary\n- uses go/ast for typesafe parsing\n- each package can have its own `binclude.FileSystem`\n- `binclude.FileSystem` implements the `http.FileSystem` interface\n- `ioutil` like functions `FileSystem.ReadFile`, `FileSystem.ReadDir`\n- include all files/ directories under a given path by calling `binclude.Include(\"./path\")`\n- include files based on a glob pattern `binclude.IncludeGlob(\"./path/*.txt\")`\n- add file paths from a textfile `binclude.IncludeFromFile(\"includefile.txt\")`\n- high test coverage\n- supports execution of executables directly from a `binclude.FileSystem` via `binexec` (os/exec wrapper)\n- optional compression of files with gzip `binclude -gzip`\n- debug mode to read files from disk `binclude.Debug = true`\n\n## Install\n```\nGO111MODULE=on go get -u github.com/lu4p/binclude/cmd/binclude\n```\n## Usage\n```go\npackage main\n\n//go:generate binclude\n\nimport (\n\t\"io/ioutil\"\n\t\"log\"\n\t\"path/filepath\"\n\n\t\"github.com/lu4p/binclude\"\n)\n\nvar assetPath = binclude.Include(\"./assets\") // include ./assets with all files and subdirectories\n\nfunc main() {\n\tbinclude.Include(\"file.txt\") // include file.txt\n\n\t// like os.Open\n\tf, err := BinFS.Open(\"file.txt\")\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n\n\tout, err := ioutil.ReadAll(f)\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n\n\tlog.Println(string(out))\n\n\t// like ioutil.Readfile\n\tcontent, err := BinFS.ReadFile(filepath.Join(assetPath, \"asset1.txt\"))\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n\n\tlog.Println(string(content))\n\n\t// like ioutil.ReadDir\n\tinfos, err := BinFS.ReadDir(assetPath)\n\tif err != nil {\n\t\tlog.Fatalln(err)\n\t}\n\n\tfor _, info := range infos {\n\t\tlog.Println(info.Name())\n\t}\n}\n\n```\nTo build use:\n```\ngo generate\ngo build\n```\n\nA more detailed example can be found [here](https://github.com/lu4p/binclude/tree/master/example).\n\n## Binary size\nThe resulting binary, with the included files can get quite large. \n\nYou can reduce the final binary size by building without debug info (`go build -ldflags \"-s -w\"`) and compressing the resulting binary with [upx](https://upx.github.io/) (`upx binname`).\n\n**Note:** If you don't need to access the compressed form of the files I would advise to just use [upx](https://upx.github.io/) and don't add seperate compression to the files. \n\nYou can add compression to the included files with `-gzip`\n\n**Note:** decompression is optional to allow for the scenario where you want to serve compressed files for a webapp directly.\n\n\n## OS / Arch Specific Includes\n\nbinclude supports including files/binaries only on specific architectures and operating systems. binclude follows the same pattern as [Go's implicit Build Constraints](https://golang.org/pkg/go/build/#hdr-Build_Constraints). It will generate files for the specific platforms like `binclude_windows.go` which contains all windows specific files.\n\nIf a file's name, matches any of the following patterns: \n```\n*_GOOS.go\n*_GOARCH.go\n*_GOOS_GOARCH.go\n```\nbinclude will consider all files included by `binclude.Include` in this file as files which should only be included on a specific GOOS and/ or GOARCH.\n\nFor example, if you want to include a binary only on Windows you could have a file `static_windows.go` and reference the static file:\n```go\npackage main\n\nimport \"github.com/lu4p/binclude\"\n\nfunc bar() {\n  binclude.Include(\"./windows-file.dll\")\n}\n```\n\nOS / Arch Specific Includes are used in the [binexec example](https://github.com/lu4p/binclude/tree/master/binexec/example).\n\n**Note:** explicit build tags like `// +build debug` are not supported for including files conditionally.\n\n## Advanced Usage\nThe generator can also be included into your package to allow for the code generator to run after all module dependencies are installed.\nWithout installing the binclude generator to the PATH seperatly.\n\nmain.go:\n```go\n// +build !gen\n\n//go:generate go run -tags=gen .\npackage main\n\nimport (\n\t\"github.com/lu4p/binclude\"\n)\n\nfunc main() {\n\tbinclude.Include(\"./assets\")\n}\n\n```\n\nmain_gen.go:\n```go\n// +build gen\n\npackage main\n\nimport (\n\t\"github.com/lu4p/binclude\"\n\t\"github.com/lu4p/binclude/bincludegen\"\n)\n\nfunc main() {\n\tbincludegen.Generate(binclude.None, \".\")\n\t// binclude.None == no compression \n\t// binclude.Gzip == gzip compression\n}\n```\n\nTo build use:\n```\ngo generate\ngo build\n```\n\n## Contributing\nIf you find a feature missing, which you consider a useful addition please open an issue. \n\nIf you plan on implementing a new feature please open an issue so we can discuss it first (I don't want you to waste your time).\n\nPull requests are welcome, and will be timely reviewed and merged, please provide tests for your code, if you don't know how to test your code open a pull request and I will suggest the right testing method.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flu4p%2Fbinclude","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flu4p%2Fbinclude","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flu4p%2Fbinclude/lists"}