From 6994400f06668c5845c687a518a7c658b1fd8c52 Mon Sep 17 00:00:00 2001 From: Nepomuk Seiler Date: Fri, 19 Dec 2014 15:50:19 +0100 Subject: [PATCH] Next iteration --- src/sphinx/formats/debian.rst | 16 ++- src/sphinx/formats/docker.rst | 12 +- src/sphinx/formats/linux.rst | 74 +++++++++- src/sphinx/formats/rpm.rst | 11 +- src/sphinx/formats/universal.rst | 237 ++++++++++++++++++++++--------- src/sphinx/formats/windows.rst | 161 +++++++++++++++------ 6 files changed, 396 insertions(+), 115 deletions(-) diff --git a/src/sphinx/formats/debian.rst b/src/sphinx/formats/debian.rst index bbbbd0c50..80b235625 100644 --- a/src/sphinx/formats/debian.rst +++ b/src/sphinx/formats/debian.rst @@ -5,7 +5,7 @@ The debian package specification is very robust and powerful. If you wish to do the underlying packaging system works. http://tldp.org/HOWTO/html_single/Debian-Binary-Package-Building-HOWTO/ is an excellent tutorial. SBT Native Packager provides two ways to build debian packages. A native one, where you need ``dpkg-deb`` installed -or a java, platform independent approach with `jdeb `_. By default the _native_ implementation +or a java, platform independent approach with `jdeb `_. By default the *native* implementation is activated. .. contents:: @@ -23,7 +23,7 @@ is activated. Requirements ------------ -If you use the _native_ debian package implementation you need the following applications installed: +If you use the *native* debian package implementation you need the following applications installed: * dpkg-deb * dpkg-sig @@ -76,7 +76,7 @@ If you want to use the java based implementation, enable the following plugin. ~~~~~~~~~~~~ For this versions debian packaging is automatically activated. -See the `Getting Started ` page for informations +See the :doc:`Getting Started ` page for informations on how to enable sbt native packager. If you want to enable `jdeb` packaging add the following to your `build.sbt` @@ -86,6 +86,16 @@ If you want to enable `jdeb` packaging add the following to your `build.sbt` packageBin in Debian <<= debianJDebPackaging in Debian +Configurations +-------------- + +Settings and Tasks inherited from parent plugins can be scoped with ``Debian``. + +.. code-block:: scala + + linuxPackageMappings in Debian := linuxPackageMappings.value + + Settings -------- diff --git a/src/sphinx/formats/docker.rst b/src/sphinx/formats/docker.rst index 2f8b2d8e2..d6a78d7b0 100644 --- a/src/sphinx/formats/docker.rst +++ b/src/sphinx/formats/docker.rst @@ -46,13 +46,23 @@ Docker images require the following setting: ~~~~~ For this versions docker packaging is automatically activated. -See the `Getting Started ` page for informations +See the :doc:`Getting Started ` page for informations on how to enable sbt native packager. +Configuration +------------- + +Settings and Tasks inherited from parent plugins can be scoped with ``Docker``. + +.. code-block:: scala + + mappings in Docker := mappings.value + Settings -------- + Informational Settings ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/src/sphinx/formats/linux.rst b/src/sphinx/formats/linux.rst index 75a20ea37..47c47a6b7 100644 --- a/src/sphinx/formats/linux.rst +++ b/src/sphinx/formats/linux.rst @@ -7,6 +7,14 @@ The native packager plugin is designed so that linux packages look similar, but .. contents:: :depth: 2 + +.. raw:: html + + Related Plugins --------------- @@ -22,6 +30,67 @@ Related Plugins Build ----- +The linux plugin is just a top level plugin for linux packaging formats. +The ``Linux`` scope contains settings which can be used by the plugins +depending on the linux plugin. + + +.. code-block:: bash + + sbt "show linux:linuxPackageMappings" + +Required Settings +~~~~~~~~~~~~~~~~~ + +A linux package needs some mandatory settings to be valid. Make sure +you have these settings in your build: + +.. code-block:: scala + + name := "Linux Example" + + version := "1.0" + + maintainer := "Max Smith " + + packageSummary := "Hello World Debian Package" + + packageDescription := """A fun package description of our software, + with multiple lines.""" + +1.0 or higher +~~~~~~~~~~~~~ + +Enable the debian plugin to activate the native package implementation. + +.. code-block:: scala + + enablePlugins(LinuxPlugin) + + +0.8 or lower +~~~~~~~~~~~~ + +For this versions linux packaging is automatically activated. +See the :doc:`Getting Started ` page for informations +on how to enable sbt native packager. + +In order to use the utility functions you need to import them with +(if you haven't alreay imported this) + +.. code-block:: scala + + import com.typesafe.sbt.SbtNativePackager._ + +Configurations +-------------- + +Settings and tasks inherited from parent plugins can be scoped with ``Linux``. + +.. code-block:: scala + + name in Linux := name.value + Settings -------- The required fields for any linux distribution are: @@ -42,8 +111,11 @@ The required fields for any linux distribution are: A list of files and their desired installation locations for the package, as well as other metainformation. +Customize +--------- + Package Mappings ----------------- +~~~~~~~~~~~~~~~~ Most of the work in generating a linux package is constructing package mappings. These 'map' a file to a location on disk where it should reside as well as information about that file. Package mappings allow the specification of file ownership, permissions and whether or not diff --git a/src/sphinx/formats/rpm.rst b/src/sphinx/formats/rpm.rst index cb5e3b3ae..4b70693e0 100644 --- a/src/sphinx/formats/rpm.rst +++ b/src/sphinx/formats/rpm.rst @@ -65,9 +65,18 @@ Enables the rpm plugin ~~~~~~~~~~~~ For this versions rpm packaging is automatically activated. -See the `Getting Started ` page for informations +See the :doc:`Getting Started ` page for informations on how to enable sbt native packager. +Configuration +------------- + +Settings and Tasks inherited from parent plugins can be scoped with ``Rpm``. + +.. code-block:: scala + + linuxPackageMappings in Rpm := linuxPackageMappings.value + Settings -------- diff --git a/src/sphinx/formats/universal.rst b/src/sphinx/formats/universal.rst index 07c177227..2e489971d 100644 --- a/src/sphinx/formats/universal.rst +++ b/src/sphinx/formats/universal.rst @@ -1,15 +1,181 @@ .. _Universal: -Universal -========= +Universal Plugin +================ Universal packaging just takes a plain ``mappings`` configuration and generates various package files for distribution. It allows you to provide your users a distribution that is not tied to any particular platform, but may require manual labor to set up. +.. contents:: + :depth: 2 + +.. raw:: html + + + +Related Plugins +--------------- + +.. toctree:: + :maxdepth: 1 + + linux.rst + windows.rst + docker.rst + + +Requirements +------------ + +Depending on what package format you want to use, you need one of the following applications installed + +* zip (if native) +* gzip +* xz +* tar +* hdiutil (for dmg) + +Build +----- + +There is a task for each output format + +Zip +~~~ + +.. code-block:: bash + + sbt universal:packageBin + +Tar +~~~ + +.. code-block:: bash + + sbt universal:packageZipTarball + +Xz +~~ + +.. code-block:: bash + + sbt universal:packageXzTarball + +Dmg +~~~ + +.. code-block:: bash + + sbt universal:packageOsxDmg + + +Required Settings +~~~~~~~~~~~~~~~~~ + +A universal has no mandatory fields. + + +1.0 or higher +~~~~~~~~~~~~~ + +Enable the universal plugin + +.. code-block:: scala + + enablePlugins(UniversalPlugin) + + +0.8 or lower +~~~~~~~~~~~~ + +For this versions universal packaging is automatically activated. +See the :doc:`Getting Started ` page for informations +on how to enable sbt native packager. + + +Configurations +-------------- + +Settings and Tasks inherited from parent plugins can be scoped with ``Universal``. + +Universal packaging provides three Configurations: + + ``universal`` + For creating full distributions + ``universal-docs`` + For creating bundles of documentation + ``universal-src`` + For creating bundles of source. + +.. code-block:: scala + + name in Universal := name.value + + name in UniversalDocs <<= name in Universal + + name in UniversalSrc <<= name in Universal + + packageName in Universal := packageName.value + +Settings +-------- +As we showed before, the Universal packages are completely configured through the use of the mappings key. Simply +specify the desired mappings for a given configuration. For Example: + +.. code-block:: scala + + mappings in Universal <+= packageBin in Compile map { p => p -> "lib/foo.jar" } + +However, sometimes it may be advantageous to customize the files for each archive separately. For example, perhaps +the .tar.gz has an additional README plaintext file in additon to a README.html. To add this just to the .tar.gz file, +use the task-scope feature of sbt: + +.. code-block:: scala + + mappings in Universal in package-zip-tarball += file("README") -> "README" + +Besides ``mappings``, the ``name``, ``sourceDirectory`` and ``target`` configurations are all respected by universal packaging. + +**Note: The Universal plugin will make anything in a bin/ directory executable. This is to work around issues with JVM +and file system manipulations.** + +Tasks +----- + + ``universal:package-bin`` + Creates the ``zip`` universal package. + + ``universal:package-zip-tarball`` + Creates the ``tgz`` universal package. + + ``universal:package-xz-tarball`` + Creates the ``txz`` universal package. The ``xz`` command can get better compression + for some types of archives. + + ``universal:package-osx-dmg`` + Creates the ``dmg`` universal package. This only work on OSX or systems with ``hdiutil``. + + ``universal-docs:package-bin`` + Creates the ``zip`` universal documentation package. + + ``universal-docs:package-zip-tarball`` + Creates the ``tgz`` universal documentation package. + + ``universal-docs:package-xz-tarball`` + Creates the ``txz`` universal documentation package. The ``xz`` command can get better compression + for some types of archives. + +Customize +--------- + Getting Started with Universal Packaging ----------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, all files found in the ``src/universal`` directory are included in the distribution. So, the first step in creating a a distribution is to place files in this directory in the layout you would like in the distributed zip file. @@ -40,7 +206,7 @@ You can use this to add anything you desire to the package. Universal Conventions ---------------------- +~~~~~~~~~~~~~~~~~~~~~ This plugin has a set of conventions for universal packages that enable the automatic generation of native packages. The universal convention has the following package layout: @@ -117,42 +283,8 @@ Notice how we're *only* modifying the package mappings for Debian linux packages :ref:`Windows` and :ref:`Linux` documentation. - -Configurations --------------- -Universal packaging provides three Configurations: - - ``universal`` - For creating full distributions - ``universal-docs`` - For creating bundles of documentation - ``universal-src`` - For creating bundles of source. - - -Settings --------- -As we showed before, the Universal packages are completely configured through the use of the mappings key. Simply -specify the desired mappings for a given configuration. For Example: - -.. code-block:: scala - - mappings in Universal <+= packageBin in Compile map { p => p -> "lib/foo.jar" } - -However, sometimes it may be advantageous to customize the files for each archive separately. For example, perhaps -the .tar.gz has an additional README plaintext file in additon to a README.html. To add this just to the .tar.gz file, -use the task-scope feature of sbt: - -.. code-block:: scala - - mappings in Universal in package-zip-tarball += file("README") -> "README" - -Besides ``mappings``, the ``name``, ``sourceDirectory`` and ``target`` configurations are all respected by universal packaging. - -**Note: The Universal plugin will make anything in a bin/ directory executable. This is to work around issues with JVM and file system manipulations.** - MappingsHelper --------------- +~~~~~~~~~~~~~~ The `MappingsHelper`_ class provides a set of helper functions to make mapping directories easier. @@ -173,7 +305,7 @@ The `MappingsHelper`_ class provides a set of helper functions to make mapping d .. _MappingsHelper: https://github.com/sbt/sbt-native-packager/blob/master/src/main/scala/com/typesafe/sbt/packager/MappingsHelper.scala Mapping Examples ----------------- +~~~~~~~~~~~~~~~~ SBT provides and IO and `Path`_ API, which lets you define custom mappings easily. The files will appear in the generate universal zip, but also in your @@ -283,28 +415,3 @@ The complete ``build.sbt`` should contain these settings if you want a single as scriptClasspath := Seq( (jarName in assembly).value ) -Commands --------- - - ``universal:package-bin`` - Creates the ``zip`` universal package. - - ``universal:package-zip-tarball`` - Creates the ``tgz`` universal package. - - ``universal:package-xz-tarball`` - Creates the ``txz`` universal package. The ``xz`` command can get better compression - for some types of archives. - - ``universal:package-osx-dmg`` - Creates the ``dmg`` universal package. This only work on OSX or systems with ``hdiutil``. - - ``universal-docs:package-bin`` - Creates the ``zip`` universal documentation package. - - ``universal-docs:package-zip-tarball`` - Creates the ``tgz`` universal documentation package. - - ``universal-docs:package-xz-tarball`` - Creates the ``txz`` universal documentation package. The ``xz`` command can get better compression - for some types of archives. diff --git a/src/sphinx/formats/windows.rst b/src/sphinx/formats/windows.rst index e685a7a77..6e6f5348a 100644 --- a/src/sphinx/formats/windows.rst +++ b/src/sphinx/formats/windows.rst @@ -1,62 +1,84 @@ .. _Windows: -Packaging for Windows -===================== +Windows Plugin +============== -The windows packaging is completely tied to the WIX installer toolset. For any non-trivial package, it's important to understand how WIX works. http://wix.tramontana.co.hu/ is an excellent tutorial to how to create packages using wix. +The windows packaging is completely tied to the WIX installer toolset. For any non-trivial package, +it's important to understand how WIX works. http://wix.tramontana.co.hu/ is an excellent tutorial +to how to create packages using wix. -However, the native-packager provides a simple layer on top of wix that *may* be enough for most projects. If it is not, just override ``wixConfig`` or ``wixFile`` settings. Let's look at the layer above direct xml configuration. +However, the native-packager provides a simple layer on top of wix that *may* be enough for most projects. +If it is not, just override ``wixConfig`` or ``wixFile`` settings. Let's look at the layer above direct +xml configuration. +.. contents:: + :depth: 2 + + +.. raw:: html -Feature configuration ---------------------- -The abstraction over wix allows you to configure "features" that users may optionally install. These feature are higher level things, like a set of files or menu links. -The currently supported compoennts of features are: + -1. Files (``ComponentFile``) -2. Path Configuration (``AddDirectoryToPath``) -3. Menu Shortcuts (``AddShortCuts``) +Requirements +------------ +You need the following applications installed -To create a new feature, simple instantiate the ``WindowsFeature`` class with the desired feature components that are included. +* `WIX Toolset `_ -Here's an example feature that installs a binary and a script, as well as path settings: +Build +----- + +.. code-block:: bash + + sbt windows:packageBin + +Required Settings +~~~~~~~~~~~~~~~~~ + +A rpm package needs some mandatory settings to be valid. Make sure +you have these settings in your build: .. code-block:: scala - wixFeatures += WindowsFeature( - id="BinaryAndPath", - title="My Project's Binaries and updated PATH settings", - desc="Update PATH environment variables (requires restart).", - components = Seq( - ComponentFile("bin/cool.bat"), - ComponentFile("lib/cool.jar"), - AddDirectoryToPath("bin")) - ) + rpmRelease := "1" + + rpmVendor := "typesafe" + + rpmUrl := Some("http://github.com/paulp/sbt-extras") + + rpmLicense := Some("BSD") + -All file references should line up exactly with those found in the ``mappings in Windows`` configuration. When generating an MSI, the plugin will first create -a directory using all the ``mappings in Windows`` and configure this for inclusion in a ``cab`` file. If you'd like to add files to include, these must *first* -be added to the mappings, and then to a feature. For example, if we complete the above setting to include file mappings, we'd have the following: +1.0 or higher +~~~~~~~~~~~~~ + +Enables the rpm plugin .. code-block:: scala - mappings in Windows ++= (packageBin in Compile, sourceDirectory in Windows) map { (jar, dir) => - Seq(jar -> "lib/cool.jar", (dir / "cool.bat") -> "bin/cool.bat") - } + enablePlugins(RpmPlugin) - wixFeatures += WindowsFeature( - id="BinaryAndPath", - title="My Project's Binaries and updated PATH settings", - desc="Update PATH environment variables (requires restart).", - components = Seq( - ComponentFile("bin/cool.bat"), - ComponentFile("lib/cool.jar"), - AddDirectoryToPath("bin")) - ) -Right now this layer is *very* limited in what it can accomplish, and hasn't been heavily debugged. If you're interested in helping contribute, please -do so! However, for most command line tools, it should be sufficient for generating a basic ``msi`` that windows users can install. +0.8 or lower +~~~~~~~~~~~~ + +For this versions rpm packaging is automatically activated. +See the :doc:`Getting Started ` page for informations +on how to enable sbt native packager. +Configuration +------------- + +Settings and Tasks inherited from parent plugins can be scoped with ``Rpm``. + +.. code-block:: scala + + linuxPackageMappings in Rpm := linuxPackageMappings.value Now, let's look at the full set of windows settings. @@ -100,17 +122,15 @@ Settings A list of file->location pairs. This list is used to move files into a location where WIX can pick up the files and generate a ``cab`` or embedded ``cab`` for the ``msi``. The WIX xml should use the relative locations in this mappings when references files for the package. -Commands --------- +Tasks +----- - ``windows:package-bin`` + ``windows:packageBin`` Creates the ``msi`` package. ``wix-file`` Generates the Wix xml file from `wixConfig` and `wixProductConfig` setings, unless overriden. -Utilities ---------- The native-packager plugin provides a few handy utilities for generating Wix XML. These utilities are located in the ``com.typesafe.packager.windows.WixHelper`` object. Among @@ -128,3 +148,56 @@ these are the following functions: ``Id`` settings for any generated components. This is a handy way to package a large directory of files for usage in the Features of an MSI. + +Customize +--------- + +Feature configuration +~~~~~~~~~~~~~~~~~~~~~ + +The abstraction over wix allows you to configure "features" that users may optionally install. These feature are higher level things, like a set of files or menu links. +The currently supported compoennts of features are: + +1. Files (``ComponentFile``) +2. Path Configuration (``AddDirectoryToPath``) +3. Menu Shortcuts (``AddShortCuts``) + + +To create a new feature, simple instantiate the ``WindowsFeature`` class with the desired feature components that are included. + +Here's an example feature that installs a binary and a script, as well as path settings: + +.. code-block:: scala + + wixFeatures += WindowsFeature( + id="BinaryAndPath", + title="My Project's Binaries and updated PATH settings", + desc="Update PATH environment variables (requires restart).", + components = Seq( + ComponentFile("bin/cool.bat"), + ComponentFile("lib/cool.jar"), + AddDirectoryToPath("bin")) + ) + +All file references should line up exactly with those found in the ``mappings in Windows`` configuration. When generating an MSI, the plugin will first create +a directory using all the ``mappings in Windows`` and configure this for inclusion in a ``cab`` file. If you'd like to add files to include, these must *first* +be added to the mappings, and then to a feature. For example, if we complete the above setting to include file mappings, we'd have the following: + +.. code-block:: scala + + mappings in Windows ++= (packageBin in Compile, sourceDirectory in Windows) map { (jar, dir) => + Seq(jar -> "lib/cool.jar", (dir / "cool.bat") -> "bin/cool.bat") + } + + wixFeatures += WindowsFeature( + id="BinaryAndPath", + title="My Project's Binaries and updated PATH settings", + desc="Update PATH environment variables (requires restart).", + components = Seq( + ComponentFile("bin/cool.bat"), + ComponentFile("lib/cool.jar"), + AddDirectoryToPath("bin")) + ) + +Right now this layer is *very* limited in what it can accomplish, and hasn't been heavily debugged. If you're interested in helping contribute, please +do so! However, for most command line tools, it should be sufficient for generating a basic ``msi`` that windows users can install.