From 1a79ec73c223059372d6bd2a9b4d4af1cfd8ee0d Mon Sep 17 00:00:00 2001 From: Jonathan Hartley Date: Fri, 21 Aug 2015 13:27:33 +0100 Subject: [PATCH 1/9] Intro paras for Freezing and Packaging Your Code I've tried to describe why you would choose one method over another, and what the relative advantages and disadvantages are of each method. I'm painfully aware that I haven't covered the combo of freezing an application *then* creating a Linux distro package of it, but maybe that's a battle for another day. My intent is to add more content on the Freezing page once this commit is accepted, so I can hear your feedback before doing any further work. Thanks. --- docs/shipping/freezing.rst | 32 ++++++++++++++---- docs/shipping/packaging.rst | 67 +++++++++++++++++++++++++++++++++++-- 2 files changed, 90 insertions(+), 9 deletions(-) diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index 9eb559e..668bdeb 100644 --- a/docs/shipping/freezing.rst +++ b/docs/shipping/freezing.rst @@ -1,19 +1,37 @@ +.. _freezing-your-code-ref: + +================== Freezing Your Code ================== -An alternative to shipping your code is freezing it — shipping it as an -executable with a bundled Python interpreter. +To 'Freeze' your code is to distribute to end-users as an executable which +includes a bundled Python interpreter. -Many applications you use every day do this: +Applications such as 'Dropbox', BitTorrent clients, 'Eve Online' and +'Civilisation IV' do this. -- Dropbox -- BitTorrent -- ... +The advantage of distributing this way is that your application will work even +if the user doesn't already have the required version of Python installed. On +Windows, and even on many Linux distributions and OSX versions, the right +version of Python will not already be installed. + +One disadvantage is that it will bloat your distribution by about 2Mb. +Another problem is that your application, once downloaded by a user, will +not receive any security updates to the version of Python it uses. + +Alternatives to Freezing +------------------------ + +:ref:`Packaging your code ` is for distributing +libraries or tools to other developers. + +On Linux, an alternative to freezing is to +:ref:`create a Linux distro package ` +(e.g. a .deb file for Debian or Ubuntu.) .. todo:: Fill in "Freezing Your Code" stub - Comparison ---------- diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 482a18c..d854c0d 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -1,13 +1,43 @@ +.. _packaging-your-code-ref: + +=================== Packaging Your Code =================== -Packaging your code is important. +Package your code to share it with other developers. For example +to share a library for other developers to use in their application, +or for development tools like 'py.test'. -You'll need to package your code first before sharing it with other developers. +An advantage of this method of distribution is its well established ecosystem +of tools such as PyPI and pip, which make it easy for other developers to +download and install your package either for casual experiments, or as part of +large, professional systems. + +It is a well-established convention for Python code to be shared this way. +If your code isn't packaged on PyPI, then it will be harder +for other developers to find it, and to use it as part of their existing +process. They will regard such projects with substantial suspicion of being +either badly managed or abandoned. + +The downside of distributing code like this is that it relies on the +recipient understanding how to install the required version of Python, +and being able and willing to use tools such as pip to install your code's +other dependencies. This is fine when distributing to other developers, but +makes this method unsuitable for distributing applications to end-uers. The `Python Packaging Guide `_ provides an extensive guide on creating and maintaining Python packages. +Alternatives to Packaging +::::::::::::::::::::::::: + +To distribute applications to end-users, you should +:ref:`freeze your application `. + +On Linux, you may also want to consider +:ref:`creating a Linux distro package ` +(e.g. a .deb file for Debian or Ubuntu.) + For Python Developers ::::::::::::::::::::: @@ -106,9 +136,42 @@ prerequisite for this is that you have an Amazon AWS account with an S3 bucket. * You can now install your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage` +.. _packaging-for-linux-distributions-ref: + For Linux Distributions :::::::::::::::::::::::: +Creating a Linux distro package is arguably the "right way" to distribute code +on Linux. + +Because a distribution package doesn't include the Python interpreter, it +makes the download and install about 2Mb smaller than +:ref:`freezing your application `. + +Also, if a distribution releases a new security update for Python, then your +application will automatically start using that new version of Python. + +However, creating and maintaining the different configurations required for +each distribution's format (e.g. .deb for Debian/Ubuntu, .rpm for Red +Hat/Fedora, etc) is a fair amount of work. If your code is an application that +you plan to distribute on other platforms, then you'll also have to create and +maintain the separate config required to freeze your application for Windows +and OSX. It would be much less work to simply create and maintain a single +config for one of the cross platform :ref:`freezing tools +`, which will produce stand-alone executables for all +distributions of Linux, as well as Windows and OSX. + +Creating a distribution package is also problematic if your code is for a +version of Python that isn't currently supported by a distribution. +Having to tell *some versions* of Ubuntu end-users that they need to add `the +'dead-snakes' PPA `_ +using `sudo apt-repository` commands before they can install your .deb file +makes for an extremely hostile user experience. Not only that, but you'd have +to maintain a custom equivalent of these instructions for every distribution, +and worse, have your users read, understand, and act on them. + +Having said all that, here's how to do it: + * `Fedora `_ * `Debian and Ubuntu `_ * `Arch `_ From 5587288b81412cb18f30408bbf160afcfc0d4536 Mon Sep 17 00:00:00 2001 From: Jonathan Hartley Date: Fri, 21 Aug 2015 13:30:50 +0100 Subject: [PATCH 2/9] Freezing: clarify how it affects Python security updates --- docs/shipping/freezing.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index 668bdeb..cdea1e6 100644 --- a/docs/shipping/freezing.rst +++ b/docs/shipping/freezing.rst @@ -16,8 +16,9 @@ Windows, and even on many Linux distributions and OSX versions, the right version of Python will not already be installed. One disadvantage is that it will bloat your distribution by about 2Mb. -Another problem is that your application, once downloaded by a user, will -not receive any security updates to the version of Python it uses. +Another problem is that your application will not receive any security updates +to the version of Python it uses unless you freeze a new version and get +users to download it. Alternatives to Freezing ------------------------ From 2914f721881a6387b6ddbc783b2ccb1348a73ba1 Mon Sep 17 00:00:00 2001 From: Jonathan Hartley Date: Fri, 21 Aug 2015 14:54:53 +0100 Subject: [PATCH 3/9] Megabyte is abbreviated 'MB', according to wikipedia --- docs/shipping/freezing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index cdea1e6..2d8b0e3 100644 --- a/docs/shipping/freezing.rst +++ b/docs/shipping/freezing.rst @@ -15,7 +15,7 @@ if the user doesn't already have the required version of Python installed. On Windows, and even on many Linux distributions and OSX versions, the right version of Python will not already be installed. -One disadvantage is that it will bloat your distribution by about 2Mb. +One disadvantage is that it will bloat your distribution by about 2MB. Another problem is that your application will not receive any security updates to the version of Python it uses unless you freeze a new version and get users to download it. From 72e00459bb202f188423f59c6b45e6838269771c Mon Sep 17 00:00:00 2001 From: Jonathan Hartley Date: Fri, 21 Aug 2015 14:56:41 +0100 Subject: [PATCH 4/9] Megabyte is abbreviated 'MB', according to wikipedia --- docs/shipping/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index d854c0d..40486c1 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -145,7 +145,7 @@ Creating a Linux distro package is arguably the "right way" to distribute code on Linux. Because a distribution package doesn't include the Python interpreter, it -makes the download and install about 2Mb smaller than +makes the download and install about 2MB smaller than :ref:`freezing your application `. Also, if a distribution releases a new security update for Python, then your From c0b377e84dda2d27f249b77f77c6ed3adef3543c Mon Sep 17 00:00:00 2001 From: Jonathan Hartley Date: Fri, 28 Aug 2015 11:01:00 +0100 Subject: [PATCH 5/9] also mention .rpm as an example Linux package --- docs/shipping/freezing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index 2d8b0e3..e333f69 100644 --- a/docs/shipping/freezing.rst +++ b/docs/shipping/freezing.rst @@ -28,7 +28,7 @@ libraries or tools to other developers. On Linux, an alternative to freezing is to :ref:`create a Linux distro package ` -(e.g. a .deb file for Debian or Ubuntu.) +(e.g. .deb files for Debian or Ubuntu, or .rpm files for Red Hat and SuSE.) .. todo:: Fill in "Freezing Your Code" stub From df345c0ca098b1ab33d528fc731582274b26e152 Mon Sep 17 00:00:00 2001 From: Jonathan Hartley Date: Fri, 28 Aug 2015 11:21:43 +0100 Subject: [PATCH 6/9] add mention of bdist_rpm --- docs/shipping/packaging.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 40486c1..18d8fd4 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -151,6 +151,9 @@ makes the download and install about 2MB smaller than Also, if a distribution releases a new security update for Python, then your application will automatically start using that new version of Python. +[Producing an RPM file using the bdist_rpm command](https://docs.python.org/3/distutils/builtdist.html#creating-rpm-packages) +for use by distributions like Red Hat or SuSE is trivially easy. + However, creating and maintaining the different configurations required for each distribution's format (e.g. .deb for Debian/Ubuntu, .rpm for Red Hat/Fedora, etc) is a fair amount of work. If your code is an application that From 62282e47e8a1724dae7708f71851f46cac51c24d Mon Sep 17 00:00:00 2001 From: Jonathan Hartley Date: Fri, 28 Aug 2015 11:33:55 +0100 Subject: [PATCH 7/9] fix markup --- docs/shipping/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 18d8fd4..064e6a9 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -151,7 +151,7 @@ makes the download and install about 2MB smaller than Also, if a distribution releases a new security update for Python, then your application will automatically start using that new version of Python. -[Producing an RPM file using the bdist_rpm command](https://docs.python.org/3/distutils/builtdist.html#creating-rpm-packages) +The `Producing an RPM file using the bdist_rpm command Date: Fri, 28 Aug 2015 11:35:21 +0100 Subject: [PATCH 8/9] fix markup again --- docs/shipping/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 064e6a9..020baed 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -151,7 +151,7 @@ makes the download and install about 2MB smaller than Also, if a distribution releases a new security update for Python, then your application will automatically start using that new version of Python. -The `Producing an RPM file using the bdist_rpm command `_ for use by distributions like Red Hat or SuSE is trivially easy. However, creating and maintaining the different configurations required for From b4f393c83ab4b34b202cfd0c0656312e6899eb4b Mon Sep 17 00:00:00 2001 From: Jonathan Hartley Date: Fri, 28 Aug 2015 11:36:35 +0100 Subject: [PATCH 9/9] fix grammar typos --- docs/shipping/packaging.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index 020baed..2fa1ca7 100644 --- a/docs/shipping/packaging.rst +++ b/docs/shipping/packaging.rst @@ -151,7 +151,7 @@ makes the download and install about 2MB smaller than Also, if a distribution releases a new security update for Python, then your application will automatically start using that new version of Python. -The `Producing an RPM file using the bdist_rpm command `_ +The bdist_rpm command makes `producing an RPM file `_ for use by distributions like Red Hat or SuSE is trivially easy. However, creating and maintaining the different configurations required for