diff --git a/docs/cli-reference.rst b/docs/cli-reference.rst new file mode 100644 index 0000000000..d698df43b6 --- /dev/null +++ b/docs/cli-reference.rst @@ -0,0 +1,417 @@ +CLI Reference +============= + +Documentation for all CLI flags + +Usage +----- + FPM [OPTIONS] [ARGS] ... + +Parameters +---------- + + [ARGS] ... + + * Inputs to the source package type. For the 'dir' type, this is the files and directories you want to include in the package. For others, like 'gem', it specifies the packages to download and use as the gem input. + +Options +------- + +* ``-t, --output-type OUTPUT_TYPE`` + - the type of package you want to create (deb, rpm, solaris, etc) +* ``-s, --input-type INPUT_TYPE`` + - The package type to use as input (gem, rpm, python, etc) +* ``-C, --chdir CHDIR`` + - Change directory to here before searching for files +* ``--prefix PREFIX`` + - A path to prefix files with when building the target package. This may not be necessary for all input packages. For example, the 'gem' type will prefix with your gem directory automatically. +* ``-p, --package OUTPUT`` + - The package file path to output. +* ``-f, --force`` + - Force output even if it will overwrite an existing file (default: false) +* ``-n, --name NAME`` + - The name to give to the package +* ``--log LEVEL`` + - Set the log level. Values: error, warn, info, debug. +* ``--verbose`` + - Enable verbose output +* ``--debug`` + - Enable debug output +* ``--debug-workspace`` + - Keep any file workspaces around for debugging. This will disable automatic cleanup of package staging and build paths. It will also print which directories are available. +* ``-v, --version VERSION`` + - The version to give to the package (default: 1.0) +* ``--iteration ITERATION`` + - The iteration to give to the package. RPM calls this the 'release'. FreeBSD calls it 'PORTREVISION'. Debian calls this 'debian_revision' +* ``--epoch EPOCH`` + - The epoch value for this package. RPM and Debian calls this 'epoch'. FreeBSD calls this 'PORTEPOCH' +* ``--license LICENSE`` + - (optional) license name for this package +* ``--vendor VENDOR`` + - (optional) vendor name for this package +* ``--category CATEGORY`` + - (optional) category this package belongs to (default: "none") +* ``-d, --depends DEPENDENCY`` + - A dependency. This flag can be specified multiple times. Value is usually in the form of: -d 'name' or -d 'name > version' +* ``--no-depends`` + - Do not list any dependencies in this package (default: false) +* ``--no-auto-depends`` + - Do not list any dependencies in this package automatically (default: false) +* ``--provides PROVIDES`` + - What this package provides (usually a name). This flag can be specified multiple times. +* ``--conflicts CONFLICTS`` + - Other packages/versions this package conflicts with. This flag can be specified multiple times. +* ``--replaces REPLACES`` + - Other packages/versions this package replaces. Equivalent of rpm's 'Obsoletes'. This flag can be specified multiple times. +* ``--config-files CONFIG_FILES`` + - Mark a file in the package as being a config file. This uses 'conffiles' in debs and %config in rpm. If you have multiple files to mark as configuration files, specify this flag multiple times. If argument is directory all files inside it will be recursively marked as config files. +* ``--directories DIRECTORIES`` + - Recursively mark a directory as being owned by the package. Use this flag multiple times if you have multiple directories and they are not under the same parent directory +* ``-a, --architecture ARCHITECTURE`` + - The architecture name. Usually matches 'uname -m'. For automatic values, you can use '-a all' or '-a native'. These two strings will be translated into the correct value for your platform and target package type. +* ``-m, --maintainer MAINTAINER`` + - The maintainer of this package. (default: "") +* ``-S, --package-name-suffix PACKAGE_NAME_SUFFIX`` + - A name suffix to append to package and dependencies, e.g.: '-git', '-bin', etc. +* ``-e, --edit`` + - Edit the package spec before building. (default: false) +* ``-x, --exclude EXCLUDE_PATTERN `` + - Exclude paths matching pattern (shell wildcard globs valid here). If you have multiple file patterns to exclude, specify this flag multiple times. +* ``--exclude-file EXCLUDE_PATH`` + - The path to a file containing a newline-sparated list of patterns to exclude from input. +* ``--description DESCRIPTION`` + - Add a description for this package. You can include '\n' sequences to indicate newline breaks. (default: "no description") +* ``--url URI`` + - Add a url for this package. (default: "http://example.com/no-uri-given") +* ``--inputs INPUTS_PATH`` + - The path to a file containing a newline-separated list of files and dirs to use as input. +* ``--after-install FILE`` + - A script to be run after package installation +* ``--before-install FILE`` + - A script to be run before package installation +* ``--after-remove FILE`` + - A script to be run after package removal +* ``--before-remove FILE`` + - A script to be run before package removal +* ``--after-upgrade FILE`` + - A script to be run after package upgrade. If not specified, --before-install, --after-install, --before-remove, and --after-remove will behave in a backwards-compatible manner (they will not be upgrade-case aware). Currently only supports deb, rpm and pacman packages. +* ``--before-upgrade FILE`` + - A script to be run before package upgrade. If not specified, --before-install, --after-install, --before-remove, and --after-remove will behave in a backwards-compatible manner (they will not be upgrade-case aware). Currently only supports deb, rpm and pacman packages. +* ``--template-scripts`` + - Allow scripts to be templated. This lets you use ERB to template your packaging scripts (for --after-install, etc). For example, you can do things like <%= name %> to get the package name. For more information, see the FPM wiki: https://github.com/jordansissel/fpm/wiki/Script-Templates +* ``--template-value KEY=VALUE`` + - Make 'key' available in script templates, so <%= key %> given will be the provided value. Implies --template-scripts +* ``--workdir WORKDIR`` + - The directory you want FPM to do its work in, where 'work' is any file copying, downloading, etc. Roughly any scratch space FPM needs to build your package. (default: "/tmp") +* ``--source-date-epoch-from-changelog`` + - Use release date from changelog as timestamp on generated files to reduce nondeterminism. Experimental; only implemented for gem so far. (default: false) +* ``--source-date-epoch-default SOURCE_DATE_EPOCH_DEFAULT`` + - If no release date otherwise specified, use this value as timestamp on generated files to reduce nondeterminism. Reproducible build environments such as dpkg-dev and rpmbuild set this via envionment variable SOURCE_DATE_EPOCH variable to the integer unix timestamp to use in generated archives, and expect tools like FPM to use it as a hint to avoid nondeterministic output. This is a Unix timestamp, i.e. number of seconds since 1 Jan 1970 UTC. See https://reproducible-builds.org/specs/source-date-epoch (default: $SOURCE_DATE_EPOCH) +* ``--gem-bin-path DIRECTORY`` + - (gem only) The directory to install gem executables +* ``--gem-package-name-prefix PREFIX`` + - (gem only) Name to prefix the package name with. (default: "rubygem") +* ``--gem-gem PATH_TO_GEM`` + - (gem only) The path to the 'gem' tool (defaults to 'gem' and searches your $PATH) (default: "gem") +* ``--gem-shebang SHEBANG`` + - (gem only) Replace the shebang in the executables in the bin path with a custom string (default: nil) +* ``--[no-]gem-fix-name`` + - (gem only) Should the target package name be prefixed? (default: true) +* ``--[no-]gem-fix-dependencies`` + - (gem only) Should the package dependencies be prefixed? (default: true) +* ``--[no-]gem-env-shebang`` + - (gem only) Should the target package have the shebang rewritten to use env? (default: true) +* ``--[no-]gem-prerelease`` + - (gem only) Allow prerelease versions of a gem (default: false) +* ``--gem-disable-dependency gem_n`` + - ame (gem only) The gem name to remove from dependency list +* ``--[no-]gem-embed-dependencies `` + - (gem only) Should the gem dependencies be installed? (default: false) +* ``--[no-]gem-version-bins`` + - (gem only) Append the version to the bins (default: false) +* ``--gem-stagingdir STAGINGDIR`` + - (gem only) The directory where FPM installs the gem temporarily before conversion. Normally a random subdirectory of workdir. +* ``--gem-git-repo GIT_REPO`` + - (gem only) Use this git repo address as the source of the gem instead of rubygems.org. (default: nil) +* ``--gem-git-branch GIT_BRANCH`` + - (gem only) When using a git repo as the source of the gem instead of rubygems.org, use this git branch. (default: nil) +* ``--[no-]deb-ignore-iteration-in-dependencies`` + - (deb only) For '=' (equal) dependencies, allow iterations on the specified version. Default is to be specific. This option allows the same version of a package but any iteration is permitted +* ``--deb-build-depends DEPENDENCY`` + - (deb only) Add DEPENDENCY as a Build-Depends +* ``--deb-pre-depends DEPENDENCY `` + - (deb only) Add DEPENDENCY as a Pre-Depends +* ``--deb-compression COMPRESSION `` + - (deb only) The compression type to use, must be one of gz, bzip2, xz, none. (default: "gz") +* ``--deb-dist DIST-TAG`` + - (deb only) Set the deb distribution. (default: "unstable") +* ``--deb-custom-control FILEPATH `` + - (deb only) Custom version of the Debian control file. +* ``--deb-config SCRIPTPATH`` + - (deb only) Add SCRIPTPATH as debconf config file. +* ``--deb-templates FILEPATH`` + - (deb only) Add FILEPATH as debconf templates file. +* ``--deb-installed-size KILOBYTES`` + - (deb only) The installed size, in kilobytes. If omitted, this will be calculated automatically +* ``--deb-priority PRIORITY`` + - (deb only) The debian package 'priority' value. (default: "extra") +* ``--[no-]deb-use-file-permissions`` + - (deb only) Use existing file permissions when defining ownership and modes +* ``--deb-user USER`` + - (deb only) The owner of files in this package (default: "root") +* ``--deb-group GROUP`` + - (deb only) The group owner of files in this package (default: "root") +* ``--deb-changelog FILEPATH`` + - (deb only) Add FILEPATH as debian changelog +* ``--[no-]deb-generate-changes`` + - (deb only) Generate PACKAGENAME.changes file. (default: false) +* ``--deb-upstream-changelog FILEPATH`` + - (deb only) Add FILEPATH as upstream changelog +* ``--deb-recommends PACKAGE`` + - (deb only) Add PACKAGE to Recommends +* ``--deb-suggests PACKAGE`` + - (deb only) Add PACKAGE to Suggests +* ``--deb-meta-file FILEPATH`` + - (deb only) Add FILEPATH to DEBIAN directory +* ``--deb-interest EVENT`` + - (deb only) Package is interested in EVENT trigger +* ``--deb-activate EVENT`` + - (deb only) Package activates EVENT trigger +* ``--deb-interest-noawait EVENT `` + - (deb only) Package is interested in EVENT trigger without awaiting +* ``--deb-activate-noawait EVENT `` + - (deb only) Package activates EVENT trigger +* ``--deb-field 'FIELD: VALUE`` + - (deb only) Add custom field to the control file +* ``--[no-]deb-no-default-config-files`` + - (deb only) Do not add all files in /etc as configuration files by default for Debian packages. (default: false) +* ``--[no-]deb-auto-config-files `` + - (deb only) Init script and default configuration files will be labeled as configuration files for Debian packages. (default: true) +* ``--deb-shlibs SHLIBS`` + - (deb only) Include control/shlibs content. This flag expects a string that is used as the contents of the shlibs file. See the following url for a description of this file and its format: http://www.debian.org/doc/debian-policy/ch-sharedlibs.html#s-shlibs +* ``--deb-init FILEPATH`` + - (deb only) Add FILEPATH as an init script +* ``--deb-default FILEPATH`` + - (deb only) Add FILEPATH as /etc/default configuration +* ``--deb-upstart FILEPATH`` + - (deb only) Add FILEPATH as an upstart script +* ``--deb-systemd FILEPATH`` + - (deb only) Add FILEPATH as a systemd script +* ``--[no-]deb-systemd-enable`` + - (deb only) Enable service on install or upgrade (default: false) +* ``--[no-]deb-systemd-auto-start `` + - (deb only) Start service after install or upgrade (default: false) +* ``--[no-]deb-systemd-restart-after-upgrade`` + - (deb only) Restart service after upgrade (default: true) +* ``--deb-after-purge FILE`` + - (deb only) A script to be run after package removal to purge remaining (config) files (a.k.a. postrm purge within apt-get purge) +* ``--[no-]deb-maintainerscripts-force-errorchecks`` + - (deb only) Activate errexit shell option according to lintian. https://lintian.debian.org/tags/maintainer-script-ignores-errors.html (default: false) +* ``--npm-bin NPM_EXECUTABLE`` + - (npm only) The path to the npm executable you wish to run. (default: "npm") +* ``--npm-package-name-prefix PREFIX`` + - (npm only) Name to prefix the package name with. (default: "node") +* ``--npm-registry NPM_REGISTRY`` + - (npm only) The npm registry to use instead of the default. +* ``--[no-]rpm-use-file-permissions`` + - (rpm only) Use existing file permissions when defining ownership and modes. +* ``--rpm-user USER`` + - (rpm only) Set the user to USER in the %files section. Overrides the user when used with use-file-permissions setting. +* ``--rpm-group GROUP`` + - (rpm only) Set the group to GROUP in the %files section. Overrides the group when used with use-file-permissions setting. +* ``--rpm-defattrfile ATTR`` + - (rpm only) Set the default file mode (%defattr). (default: "-") +* ``--rpm-defattrdir ATTR`` + - (rpm only) Set the default dir mode (%defattr). (default: "-") +* ``--rpm-rpmbuild-define DEFINITION`` + - (rpm only) Pass a --define argument to rpmbuild. +* ``--rpm-dist DIST-TAG`` + - (rpm only) Set the rpm distribution. +* ``--rpm-digest md5|sha1|sha256|sha384|sha512`` + - (rpm only) Select a digest algorithm. md5 works on the most platforms. (default: "md5") +* ``--rpm-compression-level [0-9] `` + - (rpm only) Select a compression level. 0 is store-only. 9 is max compression. (default: "9") +* ``--rpm-compression none|xz|xzmt`` + - |gzip|bzip2 (rpm only) Select a compression method. gzip works on the most platforms. (default: "gzip") +* ``--rpm-os OS`` + - (rpm only) The operating system to target this rpm for. You want to set this to 'linux' if you are using FPM on OS X, for example +* ``--rpm-changelog FILEPATH`` + - (rpm only) Add changelog from FILEPATH contents +* ``--rpm-summary SUMMARY`` + - (rpm only) Set the RPM summary. Overrides the first line on the description if set +* ``--[no-]rpm-sign`` + - (rpm only) Pass --sign to rpmbuild +* ``--[no-]rpm-auto-add-directories`` + - (rpm only) Auto add directories not part of filesystem +* ``--rpm-auto-add-exclude-directories DIRECTORIES`` + - (rpm only) Additional directories ignored by '--rpm-auto-add-directories' flag +* ``--[no-]rpm-autoreqprov`` + - (rpm only) Enable RPM's AutoReqProv option +* ``--[no-]rpm-autoreq`` + - (rpm only) Enable RPM's AutoReq option +* ``--[no-]rpm-autoprov`` + - (rpm only) Enable RPM's AutoProv option +* ``--rpm-attr ATTRFILE`` + - (rpm only) Set the attribute for a file (%attr), e.g. --rpm-attr 750,user1,group1:/some/file +* ``--rpm-init FILEPATH`` + - (rpm only) Add FILEPATH as an init script +* ``--rpm-filter-from-provides REGEX`` + - (rpm only) Set %filter_from_provides to the supplied REGEX. +* ``--rpm-filter-from-requires REGEX`` + - (rpm only) Set %filter_from_requires to the supplied REGEX. +* ``--rpm-tag TAG`` + - (rpm only) Adds a custom tag in the spec file as is. Example: --rpm-tag 'Requires(post): /usr/sbin/alternatives' +* ``--[no-]rpm-ignore-iteration-in`` + - -dependencies (rpm only) For '=' (equal) dependencies, allow iterations on the specified version. Default is to be specific. This option allows the same version of a package but any iteration is permitted +* ``--[no-]rpm-verbatim-gem-depend`` + - encies (rpm only) When converting from a gem, leave the old (FPM 0.4.x) style dependency names. This flag will use the old 'rubygem-foo' names in rpm requires instead of the redhat style rubygem(foo). (default: false) +* ``--[no-]rpm-macro-expansion`` + - (rpm only) install-time macro expansion in %pre %post %preun %postun scripts (see: https://rpm.org/user_doc/scriptlet_expansion.html) (default: false) +* ``--rpm-verifyscript FILE`` + - (rpm only) a script to be run on verification +* ``--rpm-pretrans FILE`` + - (rpm only) pretrans script +* ``--rpm-posttrans FILE`` + - (rpm only) posttrans script +* ``--rpm-trigger-before-install '[OPT]PACKAGE: FILEPATH'`` + - (rpm only) Adds a rpm trigger script located in FILEPATH, having 'OPT' options and linking to 'PACKAGE'. PACKAGE can be a comma seperated list of packages. See: http://rpm.org/api/4.4.2.2/triggers.html +* ``--rpm-trigger-after-install '[OPT]PACKAGE: FILEPATH'`` + - (rpm only) Adds a rpm trigger script located in FILEPATH, having 'OPT' options and linking to 'PACKAGE'. PACKAGE can be a comma seperated list of packages. See: http://rpm.org/api/4.4.2.2/triggers.html +* ``--rpm-trigger-before-uninstall '[OPT]PACKAGE: FILEPATH'`` + - (rpm only) Adds a rpm trigger script located in FILEPATH, having 'OPT' options and linking to 'PACKAGE'. PACKAGE can be a comma seperated list of packages. See: http://rpm.org/api/4.4.2.2/triggers.html +* ``--rpm-trigger-after-target-uninstall '[OPT]PACKAGE: FILEPATH'`` + - (rpm only) Adds a rpm trigger script located in FILEPATH, having 'OPT' options and linking to 'PACKAGE'. PACKAGE can be a comma seperated list of packages. See: http://rpm.org/api/4.4.2.2/triggers.html +* ``--cpan-perl-bin PERL_EXECUTABLE`` + - (cpan only) The path to the perl executable you wish to run. (default: "perl") +* ``--cpan-cpanm-bin CPANM_EXECUTABLE`` + - (cpan only) The path to the cpanm executable you wish to run. (default: "cpanm") +* ``--cpan-mirror CPAN_MIRROR`` + - (cpan only) The CPAN mirror to use instead of the default. +* ``--[no-]cpan-mirror-only`` + - (cpan only) Only use the specified mirror for metadata. (default: false) +* ``--cpan-package-name-prefix NAME_PREFIX`` + - (cpan only) Name to prefix the package name with. (default: "perl") +* ``--[no-]cpan-test`` + - (cpan only) Run the tests before packaging? (default: true) +* ``--[no-]cpan-verbose`` + - (cpan only) Produce verbose output from cpanm? (default: false) +* ``--cpan-perl-lib-path PERL_LIB_PATH`` + - (cpan only) Path of target Perl Libraries +* ``--[no-]cpan-sandbox-non-core `` + - (cpan only) Sandbox all non-core modules, even if they're already installed (default: true) +* ``--[no-]cpan-cpanm-force`` + - (cpan only) Pass the --force parameter to cpanm (default: false) +* ``--pear-package-name-prefix PREFIX`` + - (pear only) Name prefix for pear package (default: "php-pear") +* ``--pear-channel CHANNEL_URL`` + - (pear only) The pear channel url to use instead of the default. +* ``--[no-]pear-channel-update`` + - (pear only) call 'pear channel-update' prior to installation +* ``--pear-bin-dir BIN_DIR`` + - (pear only) Directory to put binaries in +* ``--pear-php-bin PHP_BIN`` + - (pear only) Specify php executable path if differs from the os used for packaging +* ``--pear-php-dir PHP_DIR`` + - (pear only) Specify php dir relative to prefix if differs from pear default (pear/php) +* ``--pear-data-dir DATA_DIR`` + - (pear only) Specify php dir relative to prefix if differs from pear default (pear/data) +* ``--python-bin PYTHON_EXECUTABLE`` + - (python only) The path to the python executable you wish to run. (default: "python") +* ``--python-easyinstall EASYINSTALL_EXECUTABLE`` + - (python only) The path to the easy_install executable tool (default: "easy_install") +* ``--python-pip PIP_EXECUTABLE`` + - (python only) The path to the pip executable tool. If not specified, easy_install is used instead (default: nil) +* ``--python-pypi PYPI_URL`` + - (python only) PyPi Server uri for retrieving packages. (default: "https://pypi.python.org/simple") +* ``--python-trusted-host PYPI_TRUSTED`` + - (python only) Mark this host or host:port pair as trusted for pip (default: nil) +* ``--python-package-name-prefix PREFIX`` + - (python only) Name to prefix the package name with. (default: "python") +* ``--[no-]python-fix-name`` + - (python only) Should the target package name be prefixed? (default: true) +* ``--[no-]python-fix-dependencies`` + - (python only) Should the package dependencies be prefixed? (default: true) +* ``--[no-]python-downcase-name`` + - (python only) Should the target package name be in lowercase? (default: true) +* ``--[no-]python-downcase-dependencies`` + - (python only) Should the package dependencies be in lowercase? (default: true) +* ``--python-install-bin BIN_PATH `` + - (python only) The path to where python scripts should be installed to. +* ``--python-install-lib LIB_PATH `` + - (python only) The path to where python libs should be installed to (default depends on your python installation). Want to find out what your target platform is using? Run this: python -c 'from distutils.sysconfig import get_python_lib; print get_python_lib()' +* ``--python-install-data DATA_PATH`` + - (python only) The path to where data should be installed to. This is equivalent to 'python setup.py --install-data DATA_PATH +* ``--[no-]python-dependencies`` + - (python only) Include requirements defined in setup.py as dependencies. (default: true) +* ``--[no-]python-obey-requirements-txt`` + - (python only) Use a requirements.txt file in the top-level directory of the python package for dependency detection. (default: false) +* ``--python-scripts-executable PYTHON_EXECUTABLE`` + - (python only) Set custom python interpreter in installing scripts. By default distutils will replace python interpreter in installing scripts (specified by shebang) with current python interpreter (sys.executable). This option is equivalent to appending 'build_scripts --executable PYTHON_EXECUTABLE' arguments to 'setup.py install' command. +* ``--python-disable-dependency PACKAGE_NAME`` + - (python only) The python package name to remove from dependency list (default: []) +* ``--python-setup-py-arguments SETUP_PY_ARGUMENT`` + - (python only) Arbitrary argument(s) to be passed to setup.py (default: []) +* ``--osxpkg-identifier-prefix IDENTIFIER_PREFIX`` + - (osxpkg only) Reverse domain prefix prepended to package identifier, ie. 'org.great.my'. If this is omitted, the identifer will be the package name. +* ``--[no-]osxpkg-payload-free`` + - (osxpkg only) Define no payload, assumes use of script options. (default: false) +* ``--osxpkg-ownership OWNERSHIP `` + - (osxpkg only) --ownership option passed to pkgbuild. Defaults to 'recommended'. See pkgbuild(1). (default: "recommended") +* ``--osxpkg-postinstall-action POSTINSTALL_ACTION`` + - (osxpkg only) Post-install action provided in package metadata. Optionally one of 'logout', 'restart', 'shutdown'. +* ``--osxpkg-dont-obsolete DONT_OBSOLETE_PATH`` + - (osxpkg only) A file path for which to 'dont-obsolete' in the built PackageInfo. Can be specified multiple times. +* ``--solaris-user USER`` + - (solaris only) Set the user to USER in the prototype files. (default: "root") +* ``--solaris-group GROUP`` + - (solaris only) Set the group to GROUP in the prototype file. (default: "root") +* ``--p5p-user USER`` + - (p5p only) Set the user to USER in the prototype files. (default: "root") +* ``--p5p-group GROUP`` + - (p5p only) Set the group to GROUP in the prototype file. (default: "root") +* ``--p5p-zonetype ZONETYPE`` + - (p5p only) Set the allowed zone types (global, nonglobal, both) (default: "value=global value=nonglobal") +* ``--p5p-publisher PUBLISHER`` + - (p5p only) Set the publisher name for the repository (default: "FPM") +* ``--[no-]p5p-lint`` + - (p5p only) Check manifest with pkglint (default: true) +* ``--[no-]p5p-validate`` + - (p5p only) Validate with pkg install (default: true) +* ``--freebsd-origin ABI`` + - (freebsd only) Sets the FreeBSD 'origin' pkg field (default: "FPM/") +* ``--snap-yaml FILEPATH`` + - (snap only) Custom version of the snap.yaml file. +* ``--snap-confinement CONFINEMENT`` + - (snap only) Type of confinement to use for this snap. (default: "devmode") +* ``--snap-grade GRADE`` + - (snap only) Grade of this snap. (default: "devel") +* ``--pacman-optional-depends PACKAGE`` + - (pacman only) Add an optional dependency to the pacman package. +* ``--[no-]pacman-use-file-permissions`` + - (pacman only) Use existing file permissions when defining ownership and modes +* ``--pacman-user USER`` + - (pacman only) The owner of files in this package (default: "root") +* ``--pacman-group GROUP`` + - (pacman only) The group owner of files in this package (default: "root") +* ``--pacman-compression COMPRESSION`` + - (pacman only) The compression type to use, must be one of gz, bzip2, xz, zstd, none. (default: "zstd") +* ``--pleaserun-name SERVICE_NAME `` + - (pleaserun only) The name of the service you are creating +* ``--pleaserun-chdir CHDIR`` + - (pleaserun only) The working directory used by the service +* ``--virtualenv-pypi PYPI_URL`` + - (virtualenv only) PyPi Server uri for retrieving packages. (default: "https://pypi.python.org/simple") +* ``--virtualenv-package-name-prefix PREFIX`` + - (virtualenv only) Name to prefix the package name with. (default: "virtualenv") +* ``--[no-]virtualenv-fix-name`` + - (virtualenv only) Should the target package name be prefixed? (default: true) +* ``--virtualenv-other-files-dir DIRECTORY`` + - (virtualenv only) Optionally, the contents of the specified directory may be added to the package. This is useful if the virtualenv needs configuration files, etc. (default: nil) +* ``--virtualenv-pypi-extra-url PYPI_EXTRA_URL`` + - (virtualenv only) PyPi extra-index-url for pointing to your priviate PyPi (default: nil) +* ``--[no-]virtualenv-setup-install`` + - (virtualenv only) After building virtualenv run setup.py install useful when building a virtualenv for packages and including their requirements from +* ``--[no-]virtualenv-system-site-packages`` + - (virtualenv only) Give the virtual environment access to the global site-packages +* ``--virtualenv-find-links PIP_FIND_LINKS`` + - (virtualenv only) If a url or path to an html file, then parse for links to archives. If a local path or file:// url that's a directory, then look for archives in the directory listing. (default: nil) diff --git a/docs/contributing.rst b/docs/contributing.rst index 8017a47f29..2f2390f420 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -1,33 +1,21 @@ -Want to contribute? Or need help? -================================ +Contributing/Issues +=================== -Please note that this project is released with a Contributor Code of Conduct. -By participating in this project you agree to abide by its terms. See -the `Code of Conduct`_ for details. +Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See the `Code of Conduct`_ for details. .. _Code of Conduct: https://github.com/jordansissel/fpm/blob/master/CODE_OF_CONDUCT.md -All contributions are welcome: ideas, patches, documentation, bug reports, -complaints, and even something you drew up on a napkin :) +All contributions are welcome: ideas, patches, documentation, bug reports, complaints, and even something you drew up on a napkin :) -It is more important that you are able to contribute and get help if you -need it than it is how you contribute or get help. +It is more important that you are able to contribute and get help if you need it than it is how you contribute or get help. That said, some points to get started: -* Have a problem you want fpm to solve for you? You can email the - `mailing list`_, or join the IRC channel #fpm on irc.freenode.org, or email - me personally (jls@semicomplete.com) -* Have an idea or a feature request? File a ticket on `github`_, or email the - `mailing list`_, or email me personally (jls@semicomplete.com) if that is - more comfortable. -* If you think you found a bug, it probably is a bug. File it on - `github`_ or send details to the `mailing list`_. -* If you want to send patches, best way is to fork this repo and send me a pull - request. If you don't know git, I also accept diff(1) formatted patches - - whatever is most comfortable for you. -* Want to lurk about and see what others are doing? IRC (#fpm on - irc.freenode.org) is a good place for this as is the `mailing list`_. +* Have a problem you want FPM to solve for you? You can email the `mailing list`_, or join the IRC channel #fpm on irc.freenode.org, or email me personally (jls@semicomplete.com) +* Have an idea or a feature request? File a ticket on `github`_, or email the `mailing list`_, or email me personally (jls@semicomplete.com) if that is more comfortable. +* If you think you found a bug, it probably is a bug. File it on `github`_ or send details to the `mailing list`_. +* If you want to send patches, best way is to fork this repo and send me a pull request. If you don't know git, I also accept diff(1) formatted patches - whatever is most comfortable for you. +* Want to lurk about and see what others are doing? IRC (#fpm on irc.freenode.org) is a good place for this as is the `mailing list`_. .. _mailing list: https://groups.google.com/group/fpm-users .. _github: https://github.com/jordansissel/fpm @@ -35,12 +23,12 @@ That said, some points to get started: Contributing changes by forking from GitHub ------------------------------------------- -First, create a GitHub account if you do not already have one. Log in to -GitHub and go to [the main fpm GitHub page](https://github.com/jordansissel/fpm). +First, create a GitHub account if you do not already have one. Log in to +GitHub and go to [the main FPM GitHub page](https://github.com/jordansissel/fpm). At the top right, click on the button labeled "Fork". This will put a forked -copy of the main fpm repo into your account. Next, clone your account's GitHub -repo of fpm. For example: +copy of the main FPM repo into your account. Next, clone your account's GitHub +repo of FPM. For example: $ git clone git@github.com:yourusername/fpm.git @@ -51,13 +39,13 @@ If you don't already have the bundler gem installed, install it now: $ gem install bundler -Now change to the root of the fpm repo and run: +Now change to the root of the FPM repo and run: $ bundle install -This will install all of the dependencies required for running fpm from source. +This will install all of the dependencies required for running FPM from source. Most importantly, you should see the following output from the bundle command -when it lists the fpm gem: +when it lists the FPM gem: ... Using json (1.8.1) @@ -72,14 +60,14 @@ tests will fail: yum install bsdtar -Next, run make in root of the fpm repo. If there are any problems (such as +Next, run make in root of the FPM repo. If there are any problems (such as missing dependencies) you should receive an error -At this point, the fpm command should run directly from the code in your cloned +At this point, the FPM command should run directly from the code in your cloned repo. Now simply make whatever changes you want, commit the code, and push your commit back to master. -If you think your changes are ready to be merged back to the main fpm repo, you +If you think your changes are ready to be merged back to the main FPM repo, you can generate a pull request on the GitHub website for your repo and send it in for review. @@ -93,4 +81,21 @@ you have the standalone command line tools separate from Xcode: Finally, click the install button on the prompt that appears. +Editing Documentation +--------------------- +If you want to edit the documentation, here's a quick guide to getting started: + +* Install `docker`_. +* All documentation is located in the `docs` folder. ``cd`` into the docs folder and run the following command once:: + + make docker-prep + +* Once that is done, run ``make build`` whenever you want to build the site. It will generate the html in the `_build/html` directory. +* You can use any tool like `serve _build/html` (npm package) or ``python -m http.server -d _build/html 5000`` to serve the static html on your machine (http://localhost:5000). + +.. _docker: https://docs.docker.com/engine/install/ + +Now you can simply make whatever changes you want, commit the code, and push your commit back to master. + +If you think your changes are ready to be merged back to the main FPM repo, you can generate a pull request on the GitHub website for your repo and send it in for review. diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 0000000000..9bcb2ce6df --- /dev/null +++ b/docs/getting-started.rst @@ -0,0 +1,246 @@ +Getting Started +=============== + +FPM takes your program and builds packages that can be installed easily on various operating systems. + +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 + +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. + +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 == + # + + 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 + .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 " \ + 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`` + - The ``-p`` option tells FPM what to name the package once it has been created. + - In this case, we name it ``---.``, 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 (current 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 "`` + - 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``. + +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 + +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. It will create a package named ‘node-yarn-VERSION_ARCH.deb’ with the appropriate version/arch in place. FPM will automatically pick the package name, version, maintainer, section, homepage, and description all from the npm package itself. Nothing for you to worry about :) + +Packaging a ruby gem +~~~~~~~~~~~~~~~~~~~~ + +.. note:: + This assumes you have ruby already installed on your machine. + +Run the following command:: + + fpm -s gem -t + +E.g.: To package FPM using FPM for Debian:: + + # FPM-ception :D + fpm -s gem -t deb fpm + +This will download the latest ``fpm`` rubygem from rubygems.org and convert it to a .deb. It will create a package named ‘rubygem-fpm-VERSION_ARCH.deb’ with the appropriate version/arch in place. FPM will automatically pick the package name, version, maintainer, section, homepage, and description all from the rubygem itself. Nothing for you to worry about :) + +Packaging a CPAN module +~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + This assumes you have perl already installed on your machine. + +Run the following command:: + +E.g.: To package Fennec for Debian:: + + fpm -s cpan -t deb Fennec + +This will download Fennec from CPAN and build a Debian package of the Fennec Perl module locally. + +By default, FPM believes the following to be true: + +* That your local Perl lib path will be the target Perl lib path +* That you want the package name to be prefixed with the word perl +* That the dependencies from CPAN are valid and that the naming scheme for those dependencies are prefixed with perl + +If you wish to change any of the above, use the following:: + + fpm -t deb -s cpan -–cpan-perl-lib-path /usr/share/perl5 Fennec + + fpm -t deb -s cpan --cpan-package-name-prefix fubar /usr/share/perl5 Fennec + +The first command will change the target path to where perl will be. Your local perl install may be /opt/usr/share/perl5.10 but the package will be constructed so that the module will be installed to /usr/share/perl5 + +The second command will change the prefix of the package, i.e., from perl-Fennec to fubar-Fennec. + +Configuration file +------------------- + +If you are using FPM in to build packages for multiple targets and keep repeating several options (like version, description, name, license, maintainer, url, architecture, files to package, etc.), you can add a ``.fpm`` file in your working directory, with a list of options as well as arguments that you want to pass to the CLI. Extending the example of the hello-world program, say we want to package it as a .deb and a .rpm. We could create the following .fpm file:: + + --- File: .fpm + + -s dir + --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 " + + hello-world=/usr/bin/hello-world hello-world.1=/usr/share/man/man1/hello-world.1 + +.. note:: + CLI flags will override those in the ``.fpm`` file. + +Meanwhile, we could run the following commands in terminal to build the .deb and .rpm:: + + fpm -t deb -p hello-world-0.1.0-1-any.deb + + fpm -t rpm -p hello-world-0.1.0-1-any.rpm + +Tada! You will have a .deb (for Debian) and .rpm (for RedHat), with no unnecessary duplication of metadata. You can put any other valid CLI options in the ``.fpm`` file too. + +For more detailed information regarding all CLI flags, see the :doc:`CLI reference. ` diff --git a/docs/index.rst b/docs/index.rst index d4955b1968..eadffe8c32 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,24 +1,33 @@ -fpm - packaging made simple -=========================== +FPM +=== .. note:: - The documentation here is a work-in-progress. If you want to contribute new - docs or report problems, I invite you to do so on `the project issue tracker`_. + 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`_. -.. _the project issue tracker: https://github.com/jordansissel/fpm/issues +Welcome to the FPM documentation! + +1. `Installation`_ +2. `Getting started`_ +3. `CLI reference`_ +4. `Contributing`_ -.. include:: ../README.rst +You can view the changelog `here`_. Table of Contents ----------------- .. toctree:: - :maxdepth: 2 - :includehidden: - - intro - installing - use-cases - packages - contributing - changelog + :includehidden: + + installation + getting-started + cli-reference + contributing + +.. _Installation: /installation +.. _Getting started: /getting-started +.. _CLI reference: /cli-reference +.. _Contributing: /contributing +.. _here: /changelog + +.. _the project issue tracker: https://github.com/jordansissel/fpm/issues diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 0000000000..3b1c8b4592 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,70 @@ +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. + +Installing FPM +-------------- + +.. note:: + You must have ruby installed on your machine before installing fpm. `Here` are instructions to install Ruby on your machine. + +.. _Here: https://www.ruby-lang.org/en/documentation/installation/ + +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 :doc:`using FPM! ` + +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 + +.. _issue #54: https://github.com/jordansissel/fpm/issues/54 + +.. 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 diff --git a/docs/installing.rst b/docs/installing.rst deleted file mode 100644 index 3fda1366ac..0000000000 --- a/docs/installing.rst +++ /dev/null @@ -1,98 +0,0 @@ -Installation -============ - -FPM requires a few things before you can use it. This document will show you -how to install all the necessary things :) - -Depending on what you want to do with FPM, you might need some extra things installed (like tooling to build rpms, or solaris packages, or something else), but for now, let's just get ruby so we can start using fpm! - -Installing things FPM needs --------------- - -.. warning:: - This section may be imperfect due to the inconsistencies across OS vendors - -fpm is written in Ruby, you'll need to provide Ruby. Some operating systems, -like OSX, come with Ruby already, but some do not. Depending on your operating system, you might need to run the following commands: - -On OSX/macOS:: - - brew install gnu-tar - - brew install rpm - -On Red Hat systems (Fedora 22 or older, CentOS, etc):: - - yum install ruby-devel gcc make rpm-build rubygems - -On Fedora 23 or newer:: - - dnf install ruby-devel gcc make rpm-build libffi-devel - -On Oracle Linux 7.x systems:: - - yum-config-manager --enable ol7_optional_latest - yum install ruby-devel gcc make rpm-build rubygems - -On Debian-derived systems (Debian, Ubuntu, etc):: - - apt-get install ruby ruby-dev rubygems build-essential - -Installing FPM --------------- - -You can install fpm with the `gem` tool:: - - gem install --no-document fpm - -.. note:: - `gem` is a command provided by a the Ruby packaging system called `rubygems`_. This allows you to install, and later upgrade, fpm. - -.. _rubygems: https://en.wikipedia.org/wiki/RubyGems - -You should see output that looks like this:: - - % gem install --no-ri --no-rdoc fpm - Fetching: cabin-0.9.0.gem (100%) - Successfully installed cabin-0.9.0 - Fetching: backports-3.6.8.gem (100%) - Successfully installed backports-3.6.8 - Fetching: arr-pm-0.0.10.gem (100%) - Successfully installed arr-pm-0.0.10 - Fetching: clamp-1.0.1.gem (100%) - Successfully installed clamp-1.0.1 - Fetching: ffi-1.9.14.gem (100%) - Building native extensions. This could take a while... - Successfully installed ffi-1.9.14 - Fetching: childprocess-0.5.9.gem (100%) - Successfully installed childprocess-0.5.9 - Fetching: archive-tar-minitar-0.5.2.gem (100%) - Successfully installed archive-tar-minitar-0.5.2 - Fetching: io-like-0.3.0.gem (100%) - Successfully installed io-like-0.3.0 - Fetching: ruby-xz-0.2.3.gem (100%) - Successfully installed ruby-xz-0.2.3 - Fetching: dotenv-2.1.1.gem (100%) - Successfully installed dotenv-2.1.1 - Fetching: insist-1.0.0.gem (100%) - Successfully installed insist-1.0.0 - Fetching: mustache-0.99.8.gem (100%) - Successfully installed mustache-0.99.8 - Fetching: stud-0.0.22.gem (100%) - Successfully installed stud-0.0.22 - Fetching: pleaserun-0.0.27.gem (100%) - Successfully installed pleaserun-0.0.27 - Fetching: fpm-1.6.3.gem (100%) - Successfully installed fpm-1.6.3 - 15 gems installed - -Now you should be ready to use 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.6.3 diff --git a/docs/intro.rst b/docs/intro.rst deleted file mode 100644 index 0406e6d106..0000000000 --- a/docs/intro.rst +++ /dev/null @@ -1,61 +0,0 @@ -What is FPM? -=================== - -fpm is a command-line program designed to help you build packages. - -Building a package might look something like this: - - fpm -s -t [list of sources]... - -"Source type" is what your package is coming from; a directory (dir), a rubygem -(gem), an rpm (rpm), a python package (python), a php pear module (pear), see -the `full list`_. - -.. _full list: https://fpm.readthedocs.io/en/latest/packages.html - -"Target type" is what your output package form should be. Most common are "rpm" -and "deb" but others exist (solaris, etc) - -You have a few options for learning to run FPM: - -1. If you're impatient, just scan through `fpm --help`; you'll need various - options, and we try to make them well-documented. Quick learning is - totally welcome, and if you run into issues, you are welcome to ask - questions in #fpm on freenode irc or on fpm-users@googlegroups.com! -2. `The documentation`_ has explanations and examples. If you run into - problems, I welcome you to ask questions in #fpm on freenode irc or on - fpm-users@googlegroups.com! - -.. _The documentation: http://fpm.readthedocs.io/en/latest/intro.html - -To give you an idea of what fpm can do, here's a few use cases: - -Take a directory and turn it into an RPM:: - fpm -s dir -t rpm ... - -Convert a .deb into an rpm:: - fpm -s deb -t rpm ... - -Convert a rubygem into a deb package:: - fpm -s gem -t deb ... - -Convert a .tar.gz into an OSX .pkg file:: - fpm -s tar -t osxpkg - -Convert a .zip into an rpm:: - fpm -s zip -t rpm ... - -Change properties of an existing rpm:: - fpm -s rpm -t rpm - -Create an deb that automatically installs a service:: - fpm -s pleaserun -t deb - -Below is a 10-minute video demonstrating fpm's simplicity of use: - -.. raw:: html - - - - -Now that you've seen a bit of what fpm can do, it's time to :doc:`install fpm `. diff --git a/docs/packages.rst b/docs/packages.rst deleted file mode 100644 index 5437902413..0000000000 --- a/docs/packages.rst +++ /dev/null @@ -1,9 +0,0 @@ -Packages -====== - -.. toctree:: - :maxdepth: 2 - - sources - targets - diff --git a/docs/source/dir.rst b/docs/source/dir.rst deleted file mode 100644 index 714cfdef8a..0000000000 --- a/docs/source/dir.rst +++ /dev/null @@ -1,52 +0,0 @@ -`dir` - Directories -=================== - -Synopsis:: - - fpm -s dir [other flags] path1 [path2 ...] - -The 'dir' source will package up one or more directories for you. - -Path mapping ------------- - -.. note:: - Path mapping was added in fpm version 0.4.40 - -Some times you want to take a path and copy it into a package but under a different location. fpm can use the `=` directive to mark that:: - - fpm [...] -s dir ./example/foo=/usr/bin/ - -This will put the file `foo` in the /usr/bin directory inside the package. - -A simple example of this can be shown with redis. Redis has a config file -(redis.conf) and an executable (redis-server). Let's put the executable in -/usr/bin and the config file in /etc/redis:: - - % ls src/redis-server redis.conf - src/redis-server - redis.conf - - # install src/redis-server into /usr/bin/ - # install redis.conf into /etc/redis/ - % fpm -s dir -t deb -n redis --config-files /etc/redis/redis.conf -v 2.6.10 \ - src/redis-server=/usr/bin/ \ - redis.conf=/etc/redis/ - Created deb package {:path=>"redis_2.6.10_amd64.deb"} - - % dpkg -c redis_2.6.10_amd64.deb - drwx------ jls/jls 0 2013-07-11 23:49 ./ - drwxrwxr-x jls/jls 0 2013-07-11 23:49 ./etc/ - drwxrwxr-x jls/jls 0 2013-07-11 23:49 ./etc/redis/ - -rw-rw-r-- jls/jls 24475 2013-02-11 04:24 ./etc/redis/redis.conf - drwxrwxr-x jls/jls 0 2013-07-11 23:49 ./usr/ - drwxrwxr-x jls/jls 0 2013-07-11 23:49 ./usr/bin/ - -rwxrwxr-x jls/jls 3566152 2013-02-14 11:19 ./usr/bin/redis-server - - # Did the conffiles setting work? Yep! - % dpkg-deb -e redis_2.6.10_amd64.deb . - % cat conffiles - /etc/redis/redis.conf - -Voila! - diff --git a/docs/source/gem.rst b/docs/source/gem.rst deleted file mode 100644 index 4c020db4fc..0000000000 --- a/docs/source/gem.rst +++ /dev/null @@ -1,236 +0,0 @@ -`gem` - RubyGems -================ - -Simplest invocation -------------------- - -Here's a command that will fetch the latest `json` gem and convert it to a .deb package:: - - % cd /tmp - % fpm -s gem -t deb json - ... - Created /tmp/rubygem-json-1.4.6-1.amd64.deb - -This will download the latest 'json' rubygem from rubygems.org and convert it -to a .deb. It will create a package named 'rubygem-json-VERSION_ARCH.deb' with -appropriate version/arch in place. - -Check the package:: - - % dpkg --info rubygem-json-1.4.6-1.amd64.deb - new debian package, version 2.0. - size 1004040 bytes: control archive= 335 bytes. - 275 bytes, 10 lines control - 5 bytes, 1 lines md5sums - Package: rubygem-json - Version: 1.4.6-1 - Architecture: amd64 - Maintainer: Florian Frank - Standards-Version: 3.9.1 - Section: Languages/Development/Ruby - Priority: extra - Homepage: http://flori.github.com/json - Description: JSON Implementation for Ruby - JSON Implementation for Ruby - -From the above, you can see that fpm automatically picked the package name, -version, maintainer, section, homepage, and description all from the rubygem -itself. Nothing for you to worry about :) - -Specifying a version --------------------- - -You can ask for a specific version with '-v '. It will also handle -dependencies. How about an older gem like rails 2.2.2:: - - % fpm -s gem -t deb -v 2.2.2 rails - Trying to download rails (version=2.2.2) - ... - Created .../rubygem-rails-2.2.2-1.amd64.deb - -Now observe the package created: - - % dpkg --info ./rubygem-rails-2.2.2-1.amd64.deb - new debian package, version 2.0. - size 2452008 bytes: control archive= 445 bytes. - 575 bytes, 11 lines control - 6 bytes, 1 lines md5sums - Package: rubygem-rails - Version: 2.2.2-1 - Architecture: amd64 - Maintainer: David Heinemeier Hansson - Depends: rubygem-rake (>= 0.8.3), rubygem-activesupport (= 2.2.2), - rubygem-activerecord (= 2.2.2), rubygem-actionpack (= 2.2.2), - rubygem-actionmailer (= 2.2.2), rubygem-activeresource (= 2.2.2) - Standards-Version: 3.9.1 - Section: Languages/Development/Ruby - Priority: extra - Homepage: http://www.rubyonrails.org - Description: Web-application framework with template engine, control-flow layer, and ORM. - Web-application framework with template engine, control-flow layer, and ORM. - -Noticei how the `Depends` entry for this debian package lists all the dependencies that `rails` has? - -Let's see what the package installs:: - - % dpkg -c ./rubygem-rails-2.2.2-1.amd64.deb - ... - drwxr-xr-x root/root 0 2011-01-20 17:00 ./usr/lib/ruby/gems/1.8/gems/rails-2.2.2/ - drwxr-xr-x root/root 0 2011-01-20 17:00 ./usr/lib/ruby/gems/1.8/gems/rails-2.2.2/lib/ - -rw-r--r-- root/root 3639 2011-01-20 17:00 ./usr/lib/ruby/gems/1.8/gems/rails-2.2.2/lib/source_annotation_extractor.rb - -rw-r--r-- root/root 198 2011-01-20 17:00 ./usr/lib/ruby/gems/1.8/gems/rails-2.2.2/lib/performance_test_help.rb - drwxr-xr-x root/root 0 2011-01-20 17:00 ./usr/lib/ruby/gems/1.8/gems/rails-2.2.2/lib/tasks/ - -rw-r--r-- root/root 204 2011-01-20 17:00 ./usr/lib/ruby/gems/1.8/gems/rails-2.2.2/lib/tasks/log.rake - -rw-r--r-- root/root 2695 2011-01-20 17:00 ./usr/lib/ruby/gems/1.8/gems/rails-2.2.2/lib/tasks/gems.rake - -rw-r--r-- root/root 4858 2011-01-20 17:00 ./usr/lib/ruby/gems/1.8/gems/rails-2.2.2/lib/tasks/testing.rake - -rw-r--r-- root/root 17727 2011-01-20 17:00 ./usr/lib/ruby/gems/1.8/gems/rails-2.2.2/lib/tasks/databases.rake - -Packaging individual dependencies ---------------------------------- - -A frequently-asked question is how to get a rubygem and all its dependencies -converted. Let's take a look. - -First we'll have to download the gem and its deps. The easiest way to do this -is to stage the installation in a temporary directory, like this:: - - % mkdir /tmp/gems - % gem install --no-ri --no-rdoc --install-dir /tmp/gems cucumber - - - Successfully installed json-1.4.6 - Successfully installed gherkin-2.3.3 - Successfully installed term-ansicolor-1.0.5 - Successfully installed builder-3.0.0 - Successfully installed diff-lcs-1.1.2 - Successfully installed cucumber-0.10.0 - 6 gems installed - -Now you've got everything cucumber requires to run (just as a normal 'gem -install' would.) - -`gem` saves gems to the cache directory in the gem install dir, so check it out:: - - % ls /tmp/gems/cache - builder-3.0.0.gem diff-lcs-1.1.2.gem json-1.4.6.gem - cucumber-0.10.0.gem gherkin-2.3.3.gem term-ansicolor-1.0.5.gem - -(by the way, under normal installation situations, gem would keep the cache in -a location like /usr/lib/ruby/gems/1.8/cache, see 'gem env | grep INSTALL') - -Let's convert all these gems to debs (output trimmed for sanity):: - - % find /tmp/gems/cache -name '*.gem' | xargs -rn1 fpm -d ruby -d rubygems --prefix $(gem environment gemdir) -s gem -t deb - ... - Created /tmp/gems/rubygem-json-1.4.6-1.amd64.deb - ... - Created /tmp/gems/rubygem-builder-3.0.0-1.amd64.deb - ... - Created /tmp/gems/rubygem-gherkin-2.3.3-1.amd64.deb - ... - Created /tmp/gems/rubygem-diff-lcs-1.1.2-1.amd64.deb - ... - Created /tmp/gems/rubygem-term-ansicolor-1.0.5-1.amd64.deb - ... - Created /tmp/gems/rubygem-cucumber-0.10.0-1.amd64.deb - - % ls *.deb - rubygem-builder-3.0.0-1.amd64.deb rubygem-gherkin-2.3.3-1.amd64.deb - rubygem-cucumber-0.10.0-1.amd64.deb rubygem-json-1.4.6-1.amd64.deb - rubygem-diff-lcs-1.1.2-1.amd64.deb rubygem-term-ansicolor-1.0.5-1.amd64.deb - -Nice, eh? Now, let's show what happens after these packages are installed:: - - # Show it's not install yet: - % gem list cucumber - - *** LOCAL GEMS *** - - - # Now install the .deb packages: - % sudo dpkg -i rubygem-builder-3.0.0-1.amd64.deb \ - rubygem-cucumber-0.10.0-1.amd64.deb rubygem-diff-lcs-1.1.2-1.amd64.deb \ - rubygem-gherkin-2.3.3-1.amd64.deb rubygem-json-1.4.6-1.amd64.deb \ - rubygem-term-ansicolor-1.0.5-1.amd64.deb - ... - Setting up rubygem-builder (3.0.0-1) ... - Setting up rubygem-diff-lcs (1.1.2-1) ... - Setting up rubygem-json (1.4.6-1) ... - Setting up rubygem-term-ansicolor (1.0.5-1) ... - Setting up rubygem-gherkin (2.3.3-1) ... - Setting up rubygem-cucumber (0.10.0-1) ... - - # Is it installed? - % gem list cucumber - - *** LOCAL GEMS *** - - cucumber (0.10.0) - - # Does it work? - % dpkg -L rubygem-cucumber | grep bin - /usr/lib/ruby/gems/1.8/gems/cucumber-0.10.0/bin - /usr/lib/ruby/gems/1.8/gems/cucumber-0.10.0/bin/cucumber - /usr/lib/ruby/gems/1.8/bin - /usr/lib/ruby/gems/1.8/bin/cucumber - - % /usr/lib/ruby/gems/1.8/bin/cucumber --help - Usage: cucumber [options] [ [FILE|DIR|URL][:LINE[:LINE]*] ]+ - ... - - -You can put these .deb files in your apt repo (assuming you have a local apt -repo, right?) and easily install them with 'apt-get' like: 'apt-get install -rubygem-cucumber' and expect dependencies to work nicely. - -Deterministic output --------------------- - -If convert a gem to a deb twice, you'll get different output even though the inputs didn't change: - - % fpm -s gem -t deb json - % mkdir run1; mv *.deb run1 - % sleep 1 - % fpm -s gem -t deb json - % mkdir run2; mv *.deb run2 - % cmp run1/*.deb run2/*.deb - run1/rubygem-json_2.1.0_amd64.deb run2/rubygem-json_2.1.0_amd64.deb differ: byte 124, line 4 - -This can be a pain if you're uploading packages to an apt repository -which refuses reuploads that differ in content, or if you're trying -to verify that packages have not been infected. -There are several sources of nondeterminism; use 'diffoscope run1/*.deb run2/*.deb' if you -want the gory details. See http://reproducible-builds.org for the whole story. - -To remove nondeterminism due to differing timestamps, -use the option --source-date-epoch-from-changelog; that will use the timestamp from -the gem's changelog. - -In case the gem doesn't have a standard changelog (and most don't, alas), -use --source-date-epoch-default to set a default integer Unix timestamp. -(This will also be read from the environment variable SOURCE_DATE_EPOCH if set.) - -Gems that include native extensions may have nondeterministic output -because of how the extensions get built (at least until fpm and -compilers finish implementing the reproducible-builds.org -recommendations). If this happens, use the option --gem-stagingdir=/tmp/foo. - -For instance, picking the timestamp 1234 seconds after the Unix epoch: - - % fpm -s gem -t deb --source-date-epoch-default=1234 --gem-stagingdir=/tmp/foo json - % mkdir run1; mv *.deb run1 - % sleep 1 - % fpm -s gem -t deb --source-date-epoch-default=1234 --gem-stagingdir=/tmp/foo json - % mkdir run2; mv *.deb run2 - % cmp run1/*.deb run2/*.deb - % dpkg-deb -c run1/*.deb - ... - -rw-rw-r-- 0/0 17572 1969-12-31 16:20 ./var/lib/gems/2.3.0/gems/json-2.1.0/CHANGES.md - % date --date @1234 - Wed Dec 31 16:20:34 PST 1969 - -If after using those three options, the files are still different, -you may have found a bug; we might not have plugged all the sources -of nondeterminism yet. As of this writing, these options are only -implemented for reading gems and writing debs, and only verified -to produce identical output when run twice on the same Linux system. diff --git a/docs/source/perl.rst b/docs/source/perl.rst deleted file mode 100644 index 545e966319..0000000000 --- a/docs/source/perl.rst +++ /dev/null @@ -1,38 +0,0 @@ -`cpan` - Perl packages -====================== - -A basic example: - -`fpm -t deb -s cpan Fennec` - -The above will download Fennec from CPAN and build a Debian package of the Fennec Perl module locally. - -By default, fpm believes the following to be true: - -1. That your local Perl lib path will be the target Perl lib path -2. That you want the package name to be prefixed with the word perl -3. That the dependencies from CPAN are valid and that the naming scheme for those dependencies are prefixed with perl - -If you wish to avoid any of those issues you can try: - -`fpm -t deb -s cpan --cpan-perl-lib-path /usr/share/perl5 Fennec` - -This will change the target path to where perl will be. Your local perl install may be /opt/usr/share/perl5.10 but the package will be constructed so that the module will be installed to /usr/share/perl5 - -`fpm -t deb -s cpan --cpan-package-name-prefix fubar Fennec` -This will replace the perl default prefix with fubar. The resulting package will be named in the scheme of fubar-fennec-2.10.deb - -`fpm -t -deb -s cpan --no-depends Fennec` -This will remove omit dependencies from being added to the package metadata. - -A full list of available options for CPAN are listed here:: - - --cpan-perl-bin PERL_EXECUTABLE (cpan only) The path to the perl executable you wish to run. (default: "perl") - --cpan-cpanm-bin CPANM_EXECUTABLE (cpan only) The path to the cpanm executable you wish to run. (default: "cpanm") - --cpan-mirror CPAN_MIRROR (cpan only) The CPAN mirror to use instead of the default. - --[no-]cpan-mirror-only (cpan only) Only use the specified mirror for metadata. (default: false) - --cpan-package-name-prefix NAME_PREFIX (cpan only) Name to prefix the package name with. (default: "perl") - --[no-]cpan-test (cpan only) Run the tests before packaging? (default: true) - --cpan-perl-lib-path PERL_LIB_PATH (cpan only) Path of target Perl Libraries - --[no-]cpan-sandbox-non-core (cpan only) Sandbox all non-core modules, even if they're already installed (default: true) - --[no-]cpan-cpanm-force (cpan only) Pass the --force parameter to cpanm (default: false) diff --git a/docs/source/pleaserun.rst b/docs/source/pleaserun.rst deleted file mode 100644 index e82e88642b..0000000000 --- a/docs/source/pleaserun.rst +++ /dev/null @@ -1,117 +0,0 @@ -`pleaserun` - Please, run! -=================== - -Synopsis:: - - fpm -s pleaserun [other flags] program [args...] - -The `pleaserun` source uses the pleaserun_ project to help you build a package -that installs a service. - -.. _pleaserun: http://github.com/jordansissel/pleaserun - -`pleaserun` supports the following service managers: - -* sysv, /etc/init.d/whatever -* upstart -* systemd -* runit -* launchd (OS X) - -Automatic Platform Detection ----------------------------- - -Targeting multiple platforms with a single package is hard. What init system is used? Can you predict? - -fpm+pleaserun can detect this at installation-time! - -One Package for All Platforms ------------------------------ - -The following is an example which creates an rpm that makes `redis` service -available:: - - fpm -s pleaserun -t rpm -n redis-service /usr/bin/redis-server - -The output looks like this:: - - Created package {:path=>"redis-service-1.0-1.x86_64.rpm"} - -.. note:: - Your package will detect the service platform (systemd, upstart, etc) automatically upon installation :) - -Let's see what happens when I install this on Fedora 25 (which uses systemd):: - - % sudo rpm -i redis-service-1.0-1.x86_64.rpm - Platform systemd (default) detected. Installing service. - To start this service, use: systemctl start redis-server - -And checking on our service:: - - % systemctl status redis-server - ● redis-server.service - redis-server - Loaded: loaded (/etc/systemd/system/redis-server.service; disabled; vendor pr - Active: inactive (dead) - -(It is inactive and disabled because fpm does not start it by default) - -As you can see in the above example, `fpm` added an after-install script which -detects the service manager during installation. In this case, `systemd` was -detected. - -The above example shows installing on Fedora 25, which uses systemd. You can use this same rpm package on CentOS 6, which uses upstart, and it will still work:: - - % sudo rpm -i redis-service-1.0-1.x86_64.rpm - Platform upstart (0.6.5) detected. Installing service. - To start this service, use: initctl start redis-server - -And checking on our service:: - - % initctl status redis-server - redis-server stop/waiting - -Hurray! We now have a single rpm that installs this `redis-service` service on -most systems. - -Questions You May Have ----------------------- - -How does the package know whether to use systemd, upstart, sysv, or something else? - - fpm creates a package that `does a platform check`_ when the `package is installed`_ - -.. _does a platform check: https://github.com/jordansissel/fpm/blob/master/templates/pleaserun/install.sh#L101-L113 -.. _package is installed: https://github.com/jordansissel/fpm/blob/master/templates/pleaserun/scripts/after-install.sh - -Does this mean I need ruby and pleaserun installed on the target system? - - Fortunately, no! fpm creates a package that consists only of the install scripts and the service files. The install scripts are written in bourne shell `/bin/sh`. - - Here's an example:: - - % fpm -s pleaserun -t rpm -n example /usr/bin/example - % rpm -qlp example-1.0-1.x86_64.rpm - /usr/share/pleaserun/example/generate-cleanup.sh - /usr/share/pleaserun/example/install-path.sh - /usr/share/pleaserun/example/install.sh - /usr/share/pleaserun/example/launchd/10.9/files/Library/LaunchDaemons/example.plist - /usr/share/pleaserun/example/launchd/10.9/install_actions.sh - /usr/share/pleaserun/example/systemd/default/files/etc/default/example - /usr/share/pleaserun/example/systemd/default/files/etc/systemd/system/example.service - /usr/share/pleaserun/example/systemd/default/install_actions.sh - /usr/share/pleaserun/example/sysv/lsb-3.1/files/etc/default/example - /usr/share/pleaserun/example/sysv/lsb-3.1/files/etc/init.d/example - /usr/share/pleaserun/example/upstart/0.6.5/files/etc/default/example - /usr/share/pleaserun/example/upstart/0.6.5/files/etc/init/example.conf - /usr/share/pleaserun/example/upstart/1.5/files/etc/default/example - /usr/share/pleaserun/example/upstart/1.5/files/etc/init/example.conf - - The package includes service definitions for your specific service that can - target systemd, a few versions of upstart, launchd, and sysv. - - Upon install, the `install.sh` script is run which detects the correct service - definition to install. - -Does the package clean up after itself when I remove it? - - It should. When installing, the package generates a manifest of what service files were installed, and it uses that manifest to clean up when the package is uninstalled or removed. diff --git a/docs/source/python.rst b/docs/source/python.rst deleted file mode 100644 index fedadce45d..0000000000 --- a/docs/source/python.rst +++ /dev/null @@ -1,105 +0,0 @@ -`python` - Python packages -========================== - -Minimal example ---------------- - -Here's a simple example to download the `pyramid` python package and convert it to an rpm:: - - % fpm -s python -t rpm pyramid - Trying to download pyramid (using easy_install) - Searching for pyramid - Reading http://pypi.python.org/simple/pyramid/ - Reading http://docs.pylonshq.com - Reading http://docs.pylonsproject.org - Best match: pyramid 1.0 - ... - Created /home/jls/python-pyramid-1.0.noarch.rpm - -This will download the latest 'pyramid' python module using easy_install and -convert it to an rpm. It will create a package named -'python-pyramid-VERSION_ARCH.rpm' with appropriate version/arch in place. - -Check the package:: - - % rpm -qip python-pyramid-1.0.noarch.rpm - Name : python-pyramid Relocations: (not relocatable) - Version : 1.0 Vendor: (none) - Release : 1 Build Date: Mon 16 May 2011 06:41:16 PM PDT - Install Date: (not installed) Build Host: snack.home - Group : default Source RPM: python-pyramid-1.0-1.src.rpm - Size : 2766900 License: BSD-derived (http://www.repoze.org/LICENSE.txt) - Signature : (none) - URL : http://docs.pylonsproject.org - Summary : The Pyramid web application framework, a Pylons project - Description : - The Pyramid web application framework, a Pylons project - -From the above, you can see that fpm automatically picked the package name, -version, maintainer, homepage, and description all from the python package -itself. Nothing for you to worry about :) - -Looking at the dependencies:: - - % rpm -qRp python-pyramid-1.0.noarch.rpm - python-Chameleon >= 1.2.3 - python-Mako >= 0.3.6 - python-Paste > 1.7 - python-PasteDeploy >= 0 - python-PasteScript >= 0 - python-WebOb >= 1.0 - python-repoze.lru >= 0 - python-setuptools >= 0 - python-zope.component >= 3.6.0 - python-zope.configuration >= 0 - python-zope.deprecation >= 0 - python-zope.interface >= 3.5.1 - python-venusian >= 0.5 - python-translationstring >= 0 - rpmlib(PayloadFilesHavePrefix) <= 4.0-1 - rpmlib(CompressedFileNames) <= 3.0.4-1 - -Packaging for multiple pythons -------------------------------- - -Some systems package python with packages named 'python24' and 'python26' etc. - -You can build packages like this with fpm using the `--python-package-name-prefix` flag:: - - % ruby bin/fpm -s python -t rpm --python-package-name-prefix python26 pyramid - ... - Created /home/jls/projects/fpm/python26-pyramid-1.0.noarch.rpm - - % rpm -qRp python26-pyramid-1.0.noarch.rpm - python26-Chameleon >= 1.2.3 - python26-Mako >= 0.3.6 - python26-Paste > 1.7 - python26-PasteDeploy >= 0 - - -You can ask for a specific version with '-v '. It will also handle -dependencies. Here's an example converting an older package like pysqlite version 2.5.6:: - - % fpm -s python -t rpm --python-package-name-prefix python26 -v 2.5.6 'pysqlite' - Trying to download pysqlite (using easy_install) - Searching for pysqlite==2.5.6 - Reading http://pypi.python.org/simple/pysqlite/ - Reading http://pysqlite.googlecode.com/ - < ... output cut ... > - Created /home/jls/projects/fpm/python26-pysqlite-2.5.6.x86_64.rpm - -Local python sources --------------------- - -If you are the developer of a python package, or you already have the local -package downloaded and unpacked. - -In this scenario, you can tell fpm to use the `setup.py`:: - - % ls pyramid/setup.py - pyramid/setup.py - - % fpm -s python -t rpm pyramid/setup.py - ... - Created /tmp/python-pyramid-1.0.noarch.rpm - diff --git a/docs/source/rpm.rst b/docs/source/rpm.rst deleted file mode 100644 index d93f306cd6..0000000000 --- a/docs/source/rpm.rst +++ /dev/null @@ -1,23 +0,0 @@ -`rpm` - RPM Packages -==================== - -Synopsis:: - - fpm -s rpm [other options] path-to-rpm - -Using 'rpm' as a source lets you treat an existing package as a source for -building a -new one. This can be useful for converting packages between formats or -for "editing" upstream packages. - -Strip out docs under `/usr/share/doc`:: - - fpm -t rpm -s rpm --exclude /usr/share/doc ruby-2.0.0.x86_64.rpm` - -Rename a package and assign different version:: - - fpm -t rpm -s rpm --name myruby --version $(date +%S) ruby-2.0.0.x86_64.rpm - -Convert an rpm in to a deb:: - - fpm -t deb -s rpm fpm-1.63.x86_64.rpm diff --git a/docs/source/virtualenv.rst b/docs/source/virtualenv.rst deleted file mode 100644 index 996aa87133..0000000000 --- a/docs/source/virtualenv.rst +++ /dev/null @@ -1,40 +0,0 @@ -`virtualenv` - Python virtual environments -========================================== - -Synopsis:: - - fpm -s virtualenv [other options] EGG_SPEC|requirements.txt - -FPM has support for building packages that provide a python virtualenv from a -single egg or from a `requirements.txt` file. This lets you bundle up a set of -python dependencies separate from system python that you can then distribute. - -.. note:: - `virtualenv` support requires that you have `virtualenv` and the - `virtualenv-tools` binary on your path. - - For python2 virtual environments, this can usually be achieved with `pip install virtualenv virtualenv-tools`. - - For python3 virtual environments, use `pip install virtualenv-tools3` instead. - -Example uses: -------------- - -Build an rpm package for ansible:: - - fpm -s virtualenv -t rpm ansible - yum install virtualenv-ansible*.rpm - which ansible # /usr/share/python/ansible/bin/ansible - -Create a debian package for your project's python dependencies under `/opt`:: - - echo 'glade' >> requirements.txt - echo 'paramiko' >> requirements.txt - echo 'SQLAlchemy' >> requirements.txt - fpm -s virtualenv -t deb --name myapp-python-libs \ - --prefix /opt/myapp/virtualenv requirements.txt - -Create a debian package from a version 0.9 of an egg kept in your internal -pypi repository, along with it's external dependencies:: - - fpm -s virtualenv -t deb \ - --virtualenv-pypi-extra-url=https://office-pypi.lan/ \ - proprietary-magic=0.9 diff --git a/docs/sources.rst b/docs/sources.rst deleted file mode 100644 index 4e2e3389b0..0000000000 --- a/docs/sources.rst +++ /dev/null @@ -1,10 +0,0 @@ -Sources -========= - -Sources are the things you input to fpm. - -.. toctree:: - :maxdepth: 1 - :glob: - - source/* diff --git a/docs/targets.rst b/docs/targets.rst deleted file mode 100644 index bc216fe706..0000000000 --- a/docs/targets.rst +++ /dev/null @@ -1,10 +0,0 @@ -Targets -=============== - -Targets are the output of fpm. - -.. toctree:: - :maxdepth: 1 - :glob: - - diff --git a/docs/use-cases.rst b/docs/use-cases.rst deleted file mode 100644 index 7226c08aae..0000000000 --- a/docs/use-cases.rst +++ /dev/null @@ -1,9 +0,0 @@ -Use Cases -========= - -.. toctree:: - :maxdepth: 1 - :glob: - - use-cases/* - diff --git a/docs/use-cases/files.rst b/docs/use-cases/files.rst deleted file mode 100644 index 2bcf325e7d..0000000000 --- a/docs/use-cases/files.rst +++ /dev/null @@ -1,51 +0,0 @@ -Jenkins: Single-file package -=================== - -For this example, you'll learn how to package hudson/jenkins which is a -single-file download. - -We'll use `make` to script the download, but `make` isn't required if you don't want it. - -Makefile:: - - NAME=jenkins - VERSION=2.80 - - .PHONY: package - package: - rm -f jenkins.war - wget https://updates.jenkins-ci.org/download/war/$(VERSION)/jenkins.war - fpm -s dir -t deb -n $(NAME) -v $(VERSION) --prefix /opt/jenkins jenkins.war - -.. note:: You'll need `wget` for this Makefile to work. - -Running it:: - - % make - rm -f jenkins.war - wget https://updates.jenkins-ci.org/download/war/2.80/jenkins.war - --2017-09-27 14:29:55-- https://updates.jenkins-ci.org/download/war/2.80/jenkins.war - Resolving updates.jenkins-ci.org (updates.jenkins-ci.org)... 52.202.51.185 - Connecting to updates.jenkins-ci.org (updates.jenkins-ci.org)|52.202.51.185|:443... connected. - HTTP request sent, awaiting response... 302 Found - Location: http://mirrors.jenkins-ci.org/war/2.80/jenkins.war [following] - --2017-09-27 14:29:56-- http://mirrors.jenkins-ci.org/war/2.80/jenkins.war - Resolving mirrors.jenkins-ci.org (mirrors.jenkins-ci.org)... 52.202.51.185 - Connecting to mirrors.jenkins-ci.org (mirrors.jenkins-ci.org)|52.202.51.185|:80... connected. - HTTP request sent, awaiting response... 302 Found - Location: http://ftp-nyc.osuosl.org/pub/jenkins/war/2.80/jenkins.war [following] - --2017-09-27 14:29:56-- http://ftp-nyc.osuosl.org/pub/jenkins/war/2.80/jenkins.war - Resolving ftp-nyc.osuosl.org (ftp-nyc.osuosl.org)... 64.50.233.100, 2600:3404:200:237::2 - Connecting to ftp-nyc.osuosl.org (ftp-nyc.osuosl.org)|64.50.233.100|:80... connected. - HTTP request sent, awaiting response... 200 OK - Length: 73094442 (70M) [application/x-java-archive] - Saving to: ‘jenkins.war’ - - 100%[=======================================================================================================>] 73,094,442 7.71MB/s in 11s - - 2017-09-27 14:30:07 (6.07 MB/s) - ‘jenkins.war’ saved [73094442/73094442] - - % fpm -s dir -t deb -n jenkins -v 1.396 --prefix /opt/jenkins -d "sun-java6-jre (> 0)" jenkins.war - Created .../jenkins-1.396-1.amd64.deb - -Delicious. diff --git a/docs/use-cases/make-install.rst b/docs/use-cases/make-install.rst deleted file mode 100644 index 41a98b6c4f..0000000000 --- a/docs/use-cases/make-install.rst +++ /dev/null @@ -1,75 +0,0 @@ -nodejs and multiple packages -===================================================== - -This example requires your `make install` support setting DESTDIR or otherwise -allow you to install to a specific target directory. - -Consider building nodejs. Sometimes you want to produce multiple packages from -a single project. In this case, building three separate packages: nodejs, nodejs-dev, and nodejs-doc. - -Package up the nodejs runtime ------------------------------ - -Normal build steps:: - - # Normal build steps. - % wget http://nodejs.org/dist/v0.6.0/node-v0.6.0.tar.gz - % tar -zxf node-v0.6.0.tar.gz - % cd node-v0.6.0 - % ./configure --prefix=/usr - % make - -Now install it to a temporary directory:: - - # Install to a separate directory for capture. - % mkdir /tmp/installdir - % make install DESTDIR=/tmp/installdir - -Now make the 'nodejs' package:: - - # Create a nodejs deb with only bin and lib directories: - # The 'VERSION' and 'ARCH' strings are automatically filled in for you - # based on the other arguments given. - % fpm -s dir -t deb -n nodejs -v 0.6.0 -C /tmp/installdir \ - -p nodejs_VERSION_ARCH.deb \ - -d "libssl0.9.8 > 0" \ - -d "libstdc++6 >= 4.4.3" \ - usr/bin usr/lib - -Install the package, test it out:: - - # 'fpm' just produced us a nodejs deb: - % file nodejs_0.6.0-1_amd64.deb - nodejs_0.6.0-1_amd64.deb: Debian binary package (format 2.0) - % sudo dpkg -i nodejs_0.6.0-1_amd64.deb - - % /usr/bin/node --version - v0.6.0 - -Package up the manpages (create nodejs-doc) -------------------------------------------- -Now, create a package for the node manpage:: - - # Create a package of the node manpage - % fpm -s dir -t deb -p nodejs-doc_VERSION_ARCH.deb -n nodejs-doc -v 0.6.0 -C /tmp/installdir usr/share/man - -Look in the nodejs-doc package:: - - % dpkg -c nodejs-doc_0.6.0-1_amd64.deb| grep node.1 - -rw-r--r-- root/root 945 2011-01-02 18:35 usr/share/man/man1/node.1 - -Package up the headers (create nodejs-dev) ------------------------------------------- -Lastly, package the headers for development:: - -Package up the headers via:: - - % fpm -s dir -t deb -p nodejs-dev_VERSION_ARCH.deb -n nodejs-dev -v 0.6.0 -C /tmp/installdir usr/include - % dpkg -c nodejs-dev_0.6.0-1_amd64.deb | grep -F .h - -rw-r--r-- root/root 14359 2011-01-02 18:33 usr/include/node/eio.h - -rw-r--r-- root/root 1118 2011-01-02 18:33 usr/include/node/node_version.h - -rw-r--r-- root/root 25318 2011-01-02 18:33 usr/include/node/ev.h - ... - -Yay! -