jordansissel · jordansissel · Aug 16, 2021 · Aug 3, 2021 · Aug 3, 2021 · Aug 5, 2021
diff --git a/docs/cli-reference.rst b/docs/cli-reference.rst
diff --git a/docs/contributing.rst b/docs/contributing.rst
@@ -1,46 +1,34 @@
-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
 
 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
@@ -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 <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``
+	- 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 (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 <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``.
+
+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. 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 <deb/rpm/pacman/solaris/freebsd/osxpkg/tar> <gem-name>
+
+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 <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
+
+.. 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. <cli-reference>`