fpm Documentation Release 1.9.0 Jordan Sissel Sep 22, 2021 Contents 1 Table of Contents 3 1.1 Installation................................................3 1.2 Getting Started..............................................4 1.3 FPM Command-line Reference..................................... 10 1.4 Contributing/Issues............................................ 34 i ii fpm Documentation, Release 1.9.0 Note: The documentation here is a work-in-progress; it is by no means extensive. If you want to contribute new docs or report problems, you are invited to do so on the project issue tracker. Welcome to the FPM documentation! 1. Installation 2. Getting started 3. CLI reference 4. Contributing You can view the changelog here. Contents 1 fpm Documentation, Release 1.9.0 2 Contents CHAPTER 1 Table of Contents 1.1 Installation FPM is written in ruby and can be installed using gem. For some package formats (like rpm and snap), you will need certain packages installed to build them. 1.1.1 Installing FPM Note: You must have ruby installed on your machine before installing fpm. Here are instructions to install Ruby on your machine. You can install FPM with the gem tool: gem install fpm To make sure fpm is installed correctly, try running the following command: fpm--version You should get some output like this, although the exact output will depend on which version of FPM you have installed.: % fpm--version 1.13.1 Now you can go on to using FPM! 3 fpm Documentation, Release 1.9.0 1.1.2 Installing optional dependencies Warning: This section may be imperfect; please make sure you are installing the right package for your OS. Some package formats require other tools to be installed on your machine to be built; especially if you are building a package for another operating system/distribution. • RPM: rpm/rpm-tools/rpm-build [This dependency might be removed in the future, see issue #54 on github] • Snap: squashfs/squashfs-tools Note: You will not be able to build an osxpkg package (.pkg) for MacOS unless you are running MacOS. Here are instructions to install these dependencies on your machine: On OSX/macOS: brew install rpm squashfs On Arch Linux and Arch-based systems (Manjaro, EndeavourOS, etc): pacman-S rpm-tools squashfs-tools On Debian and Debian-based systems (Ubuntu, Linux Mint, Pop!_OS, etc): apt-get install squashfs-tools On Red Hat systems (Fedora 22 or older, CentOS, Rocky Linux, etc): yum install rpm-build squashfs-tools On Fedora 23 or newer: dnf install rpm-build squashfs-tools On Oracle Linux 7.x systems: yum-config-manager--enable ol7_optional_latest yum install rpm-build squashfs-tools 1.2 Getting Started FPM takes your program and builds packages that can be installed easily on various operating systems. 1.2.1 Understanding the basics of FPM The fpm command takes in three arguments: • The type of sources to include in the package • The type of package to output • The sources themselves 4 Chapter 1. Table of Contents fpm Documentation, Release 1.9.0 The source could be a: • file OR a directory with various files needed to run the program - dir • nodejs (npm) package - npm • ruby (gem) package - gem • python (using easy_install or a local setup.py) package - python • python virtualenv - virtualenv • pear package - pear • pearl (cpan) module - cpan • .deb package - deb • .rpm package - rpm • pacman (.pkg.tar.zst) package - pacman • .pkgin package - pkgin • package without any files (useful for meta packages) - empty The target (output package format) could be: • A .deb package (for Debian and Debian-based) - deb • A .rpm package (for RedHat based) - rpm • A .solaris package (for Solaris) - solaris • A .freebsd package (for FreeBSD) - freebsd • MacOS .pkg files - osxpkg • Pacman packages (.pkg.tar.zst) (for Arch Linux and Arch-based) - pacman • A puppet module - puppet • A p5p module - p5p • A self-extracting installer - sh • A tarfile that can be extracted into the root of any machine to install the program - tar • A zipfile that can be extracted into the root of any machine to install the program - zip • A directory that can be copied to the root of any machine to install the program - dir Given a source and a target, FPM can convert all the source files into a package of the target format. 1.2.2 Using it to package an executable To simplyify things a bit, let’s take an example. Suppose you have a bash script that prints ‘Hello, world!’ in multiple colors when it is run: --- File: hello-world #!/usr/bin/env bash # # == hello-world 0.1.0 == # (continues on next page) 1.2. Getting Started 5 fpm Documentation, Release 1.9.0 (continued from previous page) echo"Hello, world!"| lolcat Let’s say you even wrote a manpage (manual page) for it: --- File: hello-world.1 .TH HELLO WORLD"1""July 2021""hello-world 0.1.0""User Commands" .SH NAME hello-world \- manual page for hello-world 0.1.0 .SH DESCRIPTION .IP USAGE: hello-world .SH"SEE ALSO" .IP Website: https://example.com/hello-world .SH"OTHER" .IP Made by You The Amazing Person<you are an amazing person at example dot com> .IP This program is distributed under the AGPL 3.0 license. Now you want to package this script and its manual page and distribute to the world as a .deb file. To do that using FPM, here is the command we need to run: fpm \ -s dir-t deb \ -p hello-world-0.1.0-1-any.deb \ --name hello-world \ --license agpl3 \ --version 0.1.0\ --architecture all\ --depends bash--depends lolcat \ --description"Say hi!"\ --url"https://example.com/hello-world"\ --maintainer"You The Amazing Person <you are an amazing person at example dot com> ,!"\ hello-world=/usr/bin/hello-world hello-world.1=/usr/share/man/man1/hello-world.1 If you have installed FPM, and have the hello-world script in your current directory, you should be able to see a hello-world-0.1.0-1-any.deb file in your current directory after you run this command. Let’s break the command down, option by option: • -s dir [required] – The -s option tells FPM what sources to use to build the package. – In this case [dir], we are telling FPM that we want to build a package from source files that we have on our computer. • -t deb [required] – The -t option tells FPM what type of package to build (target package). – In this case [deb], we are telling FPM that we want to build a .deb package, that can be installed on Debian and Debian-based operating systems, such as Ubuntu. • -p hello-world-0.1.0-1-any.deb 6 Chapter 1. Table of Contents fpm Documentation, Release 1.9.0 – The -p option tells FPM what to name the package once it has been created. – In this case, we name it <package name>-<version>-<package rel/ iteration>-<architecture>.<file extension>, but you can call it whatever you want. • --name hello-world – The name of the program that FPM is packaging. – In this case, it is hello-world. • --license agpl3 – The license the program uses – In this case, we use the AGPL 3.0 license (If you have a custom license, use custom instead of AGPL3) • --version 0.1.0 – The version of the program – In this case, the version is 0.1.0 • --architecture all – The architecture required to run the program [valid values are: x86_64/amd64, aarch64, native (cur- rent architecture), all/noarch/any] – In this case, the program is just a bash script, so we can run on all architectures • --depends bash --depends lolcat – The dependencies the program needs to run – In this case, we need bash and lolcat - bash to run the program itself, and lolcat to display the text in multiple colors • --description "Say hi!" – The program description – In this case, it is Say hi! • --url "https://example.com/hello-world" – The URL to the program‘‘s website or URL to program source • --maintainer "You The Amazing Person <you are an amazing person at example dot com>" – The name and (optionally) email of the person creating the package • hello-world=/usr/bin/hello-world hello-world.1=/usr/share/man/man1/hello-world.1 [required] – This is the most important part. It tells FPM which file (relative paths from the current directory) should be installed to which path in the machine. – In this case, we want the user to be able to execute the command hello-world from terminal; so we put the hello-world script in the user’s PATH, that is, in /usr/bin/. We also want the user to access the manual page using man hello-world, so we put the manpage (hello-world.1) in the /usr/share/man/man1/ directory. For more detailed documentation about each and every flag (there are some package-type-specific flags that exist as well), run fpm --help. 1.2. Getting Started 7 fpm Documentation, Release 1.9.0 1.2.3 Using it to package an existing package We’ve seen how to package a program if you have an executable, but what if you already have a program that you have not written as an executable script, but in a language like nodejs instead? FPM can help here too. It can take any nodejs package, ruby gem or even a python package and turn it into a deb, rpm, pacman, etc. package. Here are a couple of examples. Packaging a NodeJS application that’s already on NPM Note: This assumes you have nodejs and npm already installed on your machine. Run the following command: fpm-s npm-t<deb/rpm/pacman/solaris/freebsd/osxpkg/tar><npm-package-name> E.g.: To package yarn for Arch Linux: fpm-s npm-t pacman yarn This will download the latest yarn package from npm.com and convert it to a .pkg.tar.zst (pacman) package.