mirror/ nfpm
1
1
Fork 0
mirror of https://github.com/goreleaser/nfpm synced 2024-05-10 04:26:19 +02:00
Code Issues Releases Activity

docs: improve documentation 

Signed-off-by: Carlos Alexandro Becker <caarlos0@gmail.com>
This commit is contained in:
Carlos Alexandro Becker 2020-07-10 02:06:39 -03:00
parent 397d266f18
commit 32bdb10f6b
6 changed files with 161 additions and 176 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
README.md
View File

@ -15,61 +15,19 @@
## Why
While [fpm][] is great, for me it is a bummer that it depends on Ruby, tar
and probably other software.
While [fpm][] is great, for me, it is a bummer that it depends on `ruby`, `tar`
and other softwares.
I wanted something that could be used as a binary and/or as a lib on go-software,
so I hacked this together and it works!
I wanted something that could be used as a binary and/or as a library and that
was really simple.
## Goals
* [x] be simple to use
* [x] provide packaging for the most common linux packaging systems (at very least deb and rpm)
* [x] be distributed as a single binary
* [x] reproducible results
* [x] depend on the fewer external things as possible
* [x] generate packages based on yaml files (maybe also json and toml?)
* [x] be possible to use it as a lib in other go projects (namely [goreleaser][] itself)
* [ ] support complex packages and power users
So I created NFPM: a simpler, 0-dependency, as-little-assumptions-as-possible alternative to fpm.
## Usage
The first steps are to run `nfpm init` to initialize a config file and edit
the generated file according to your needs:
Check the documentation at https://nfpm.goreleaser.com
![nfpm init](https://user-images.githubusercontent.com/245435/36346101-f81cdcec-141e-11e8-8afc-a5eb93b7d510.png)
The next step is to run `nfpm pkg --target mypkg.deb`.
NFPM will guess which packager to use based on the target file extension.
![nfpm pkg](https://user-images.githubusercontent.com/245435/36346100-eaaf24c0-141e-11e8-8345-100f4d3ed02d.png)
And that's it!
## Usage as a docker image
You can run it with docker as well:
```sh
docker run --rm \
-v $PWD:/tmp/pkg \
goreleaser/nfpm pkg --config /tmp/pkg/foo.yml --target /tmp/pkg/foo.rpm
```
That's it!
## Usage as lib
You can look at the code of nfpm itself to see how to use it as a library, or, take
a look at the [nfpm pipe on GoReleaser](https://github.com/goreleaser/goreleaser/blob/master/internal/pipe/nfpm/nfpm.go).
> **Attention**: GoReleaser `deb` packager only compiles with go1.10+.
## Status
* both deb and rpm packaging are working but there are some missing features.
## Special thanks
## Special thanks 🙏
Thanks to the [fpm][] authors for fpm, which inspires nfpm a lot.

5
cmd/nfpm/main.go
View File

@ -118,10 +118,13 @@ func doPackage(configPath, target, packager string) error {
}
const example = `# nfpm example config file
#
# check https://nfpm.goreleaser.com/configuration for detailed usage
#
name: "foo"
arch: "amd64"
platform: "linux"
version: "v${MY_APP_VERSION}"
version: "v1.0.0"
section: "default"
priority: "extra"
replaces:

130
www/docs/configuration.md Normal file
View File

@ -0,0 +1,130 @@
# Configuration
A commented out `nfpm.yaml` config file example:
```yaml
# Name. (required)
name: foo
# Architecture. (required)
arch: amd64
# Platform.
# Defaults to `linux`.
platform: linux
# Version. (required)
version: v1.2.3
# Version Epoch.
# Default is extracted from `version` if it is semver compatible.
epoch: 2
# Version Release.
# Default is extracted from `version` if it is semver compatible.
release: 1
# Version Prerelease.
# Default is extracted from `version` if it is semver compatible.
prerelease: beta1
# Section.
section: default
# Priority.
priority: extra
# Maintaner.
maintainer: Carlos Alexandro Becker <root@carlosbecker.com>
# Description.
# Defaults to `no description given`.
description: Sample package
# Vendor.
vendor: GoReleaser
# Package's homepage.
homepage: https://nfpm.goreleaser.com
# License.
license: MIT
# Packages it replaces. (overridable)
replaces:
- foobar
# Packages it provides. (overridable)
provides:
- bar
# Dependencies. (overridable)
depends:
- git
# Recommended packages. (overridable)
recommends:
- golang
# Suggested packages. (overridable)
suggests:
- bzr
# Packages it conflicts with. (overridable)
conflicts:
- mercurial
# Files to add to the package. (overridable)
# This can be binaries or any other files.
#
# Key is the local file, value is the path inside the package.
files:
path/to/local/foo: /usr/local/bin/foo
# Config files are dealt with differently when upgrading and uninstalling the
# package. (overridable)
#
# Key is the local file, value is the path inside the package
config_files:
path/to/local/foo.con: /etc/foo.conf
# Empty folders your package may need created. (overridable)
empty_folders:
- /var/log/foo
# Scripts to run at specific stages. (overridable)
scripts:
preinstall: ./scripts/preinstall.sh
postinstall: ./scripts/postinstall.sh
preremove: ./scripts/preremove.sh
postremove: ./scripts/postremove.sh
# Custon configuration applied only to the RPM packager.
# All fields described bellow, plus all fields above marked as `overridable`
# can be specified here.
rpm:
# Group.
group: root
# Compression algorithm.
compression: lzma
# Custon configuration applied only to the Deb packager.
# All fields described bellow, plus all fields above marked as `overridable`
# can be specified here.
deb:
# Custom version metadata.
# Default is extracted from `version` if it is semver compatible.
metadata: xyz2
# Custom deb rules script.
scripts:
rules: foo.sh
```
## Templating
Templating is not and will not be supported.
If you really need it, you can build on top of NFPM, use `envsubst`, `jsonnet`
or something apply it on top of it.

10
www/docs/index.md
View File

@ -1,15 +1,17 @@
# Home
NFPM is a simple Deb and RPM packager without external dependencies.
NFPM is a simple Deb and RPM packager with 0 external dependencies.
![](https://user-images.githubusercontent.com/245435/36346100-eaaf24c0-141e-11e8-8345-100f4d3ed02d.png)
## Why
While [fpm][] is great, for me it is a bummer that it depends on `ruby`, `tar`
While [fpm][] is great, for me, it is a bummer that it depends on `ruby`, `tar`
and other softwares.
I wanted something that could be used as a binary and/or as a library, so
I hacked this together - it works!
I wanted something that could be used as a binary and/or as a library and that
was really simple.
So I created NFPM: a simpler, 0-dependency, as-little-assumptions-as-possible alternative to fpm.
[fpm]: https://github.com/jordansissel/fpm

135
www/docs/usage.md
View File

@ -1,5 +1,7 @@
# Usage
## Command Line
To create a sample config file, run:
```console
@ -9,128 +11,17 @@ $ nfpm init
You can then customize it and package to the formats you want:
```console
$ nfpm pkg --target foo.deb
$ nfpm pkg --target foo.rpm
$ nfpm pkg --packager deb --target /tmp/
using deb packager...
created package: /tmp/foo_1.0.0_amd64.deb
$ nfpm pkg --packager rpm --target /tmp/
using rpm packager...
created package: /tmp/foo-1.0.0.x86_64.rpm
```
## Configuration
## Go Library
```yaml
# Name. (required)
name: foo
# Architecture. (required)
arch: amd64
# Platform.
# Defaults to `linux`.
platform: linux
# Version. (required)
version: v1.2.3
# Version Epoch.
# Default is extracted from `version` if it is semver compatible.
epoch: 2
# Version Release.
# Default is extracted from `version` if it is semver compatible.
release: 1
# Version Prerelease.
# Default is extracted from `version` if it is semver compatible.
prerelease: beta1
# Section.
section: default
# Priority.
priority: extra
# Maintaner.
maintainer: Carlos Alexandro Becker <root@carlosbecker.com>
# Description.
# Defaults to `no description given`.
description: Sample package
# Vendor.
vendor: GoReleaser
# Package's homepage.
homepage: https://nfpm.goreleaser.com
# License.
license: MIT
# Packages it replaces. (overridable)
replaces:
- foobar
# Packages it provides. (overridable)
provides:
- bar
# Dependencies. (overridable)
depends:
- git
# Recommended packages. (overridable)
recommends:
- golang
# Suggested packages. (overridable)
suggests:
- bzr
# Packages it conflicts with. (overridable)
conflicts:
- mercurial
# Files to add to the package. (required if no `config_files` were provided) (overridable)
# This can be binaries or any other files.
#
# Key is the local file, value is the path inside the package.
files:
path/to/local/foo: /usr/local/bin/foo
# Config files are dealt with differently when upgrading and uninstalling the
# package. (required if no `files` were provided) (overridable)
#
# Key is the local file, value is the path inside the package
config_files:
path/to/local/foo.con: /etc/foo.conf
# Empty folders your package may need created. (overridable)
empty_folders:
- /var/log/foo
# Scripts to run at specific stages. (overridable)
scripts:
preinstall: ./scripts/preinstall.sh
postinstall: ./scripts/postinstall.sh
preremove: ./scripts/preremove.sh
postremove: ./scripts/postremove.sh
# Custon configuration applied only to the RPM packager.
# All fields described bellow, plus all fields above marked as `overridable`
# can be specified here.
rpm:
# Group.
group: root
# Compression algorithm.
compression: lzma
# Custon configuration applied only to the Deb packager.
# All fields described bellow, plus all fields above marked as `overridable`
# can be specified here.
deb:
# Custom version metadata.
# Default is extracted from `version` if it is semver compatible.
metadata: xyz2
# Custom deb rules script.
scripts:
rules: foo.sh
```
Check the [GoDocs](https://pkg.go.dev/github.com/goreleaser/nfpm?tab=doc) page,
as well as [NFPM command line implementation](https://github.com/goreleaser/nfpm/blob/master/cmd/nfpm/main.go)
and [GoReleaser's usage](https://github.com/goreleaser/goreleaser/blob/master/internal/pipe/nfpm/nfpm.go).

1
www/mkdocs.yml
View File

@ -38,6 +38,7 @@ nav:
- index.md
- install.md
- usage.md
- configuration.md
- contributing.md
- sponsors.md