From e8196c104fffeec01359950eb472f636c7ef1294 Mon Sep 17 00:00:00 2001 From: Alex Kavanagh Date: Tue, 8 Nov 2022 12:34:42 +0000 Subject: [PATCH 1/2] Add a deprecation/status message to the README This is to effectively disuade people to use it and get them to look elsewhere for writing new charms (i.e. point them to the Operator Framework). Also add details of which track to use for which version of charms. --- README.rst | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 74 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index a80c6838..7c4f7ea2 100644 --- a/README.rst +++ b/README.rst @@ -13,9 +13,82 @@ home page for more information. https://jujucharms.com/ +STATUS +====== + +charm-tools is now largely in *maintenance mode*, as the charms.reactive method +of building charms is deprecated in favour of using the `operator +framework `_. This means that, generally, only bug +fixes or features required to make charm-tools work better with charmcraft will +be considered. + +charm-tools should only be used to maintain existing charms.reactive charms, +and not to start *new* charms. The `operator framework +`_ should be used for new charms. + +Also, it is increasingly more difficult to get a single Python code base to +build source charms that will work across Xenial to Jammy+ (e.g. Python 3.5 to +Python 3.10) due to Python versions < 3.7 being EOL. There are a number of +strategies to deal with that, and it generally involves pinning python modules +for various different versions of Python when building the charm. As the +`charmhub `_ supports architecture-specific builds of +charms, charm-tools also offers binary charms, which are charms with +pre-compiled binary wheels that do not need build environments on the target +system. See ``charm build --help`` for more details. + +charm-tools is available as a snap and can be used within a ``charmcraft.yaml`` +to build a reactive charm suitable for uploading to the +`charmhub `_: + +.. code-block:: yaml + + type: charm + + parts: + charm: + source: src/ + plugin: reactive + build-snaps: + - charm/3.x/stable + build-environment: + - CHARM_INTERFACES_DIR: /root/project/interfaces/ + - CHARM_LAYERS_DIR: /root/project/layers/ + + bases: + - build-on: + - name: ubuntu + channel: "22.04" + architectures: + - amd64 + run-on: + - name: ubuntu + channel: "22.04" + architectures: [amd64, s390x, ppc64el, arm64] + - name: ubuntu + channel: "22.10" + architectures: [amd64, s390x, ppc64el, arm64] + +Note that this ``charmcraft.yaml`` specifies the 3.x track for charm-tools, as +it's building on the 22.04 base (jammy) which is Python 3.10. + +Snap Tracks/Version +------------------- + +Due to the complexity of building reactive charms across multiple Python +versions, the tool has been split into two tracks: + +1. For charms targetting Ubuntu focal (20.04) or earlier: 2.x +2. For charms targetting Ubuntu jammy (22.04) or later: 3.x + +Other charms.reactive projects +------------------------------ + +* `layer-basic `_ - the base layer in all ``charms.reactive`` charms. +* `charms.reactive `_ - core libraries used in building reactive charms. +* `layer-index `_ - formal layer index. Installation ------------- +============ To run the latest stable release, use:: From 370b80e25ed5cb05c7d6bcca5b95f8557de60ba0 Mon Sep 17 00:00:00 2001 From: Alex Kavanagh Date: Tue, 7 Feb 2023 11:28:19 +0000 Subject: [PATCH 2/2] Update readme following review comments These correct the bases section, add a binary wheels section and re-drafts the reasoning behind the 2.x/3.x split for snap tracks. --- README.rst | 54 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 45 insertions(+), 9 deletions(-) diff --git a/README.rst b/README.rst index 7c4f7ea2..dba64185 100644 --- a/README.rst +++ b/README.rst @@ -51,34 +51,70 @@ to build a reactive charm suitable for uploading to the build-snaps: - charm/3.x/stable build-environment: - - CHARM_INTERFACES_DIR: /root/project/interfaces/ - - CHARM_LAYERS_DIR: /root/project/layers/ + - CHARM_INTERFACES_DIR: $CRAFT_PROJECT_DIR/interfaces/ + - CHARM_LAYERS_DIR: $CRAFT_PROJECT_DIR/layers/ bases: - build-on: - name: ubuntu channel: "22.04" - architectures: - - amd64 + architectures: [amd64] run-on: - name: ubuntu channel: "22.04" - architectures: [amd64, s390x, ppc64el, arm64] + architectures: [amd64] + - build-on: + - name: ubuntu + channel: "22.04" + architectures: [arm64] + run-on: + - name: ubuntu + channel: "22.04" + architectures: [arm64] + - build-on: + - name: ubuntu + channel: "22.04" + architectures: [ppc64el] + run-on: - name: ubuntu - channel: "22.10" - architectures: [amd64, s390x, ppc64el, arm64] + channel: "22.04" + architectures: [ppc64el] + - build-on: + - name: ubuntu + channel: "22.04" + architectures: [s390x] + run-on: + - name: ubuntu + channel: "22.04" + architectures: [s390x] Note that this ``charmcraft.yaml`` specifies the 3.x track for charm-tools, as it's building on the 22.04 base (jammy) which is Python 3.10. +Binary builds +------------- + +To help with reducing the installation dependencies of python modules on the +runtime systems, binary wheels may be built. These are architecture-dependent +and so the 'build-on/run-on' bases specification (as shown above) **must** be +used if the charm must support multiple architectures. An example of when a +binary wheel is preferable is for the cryptography module, which, for recent +releases, requires a rust compiler installed on the target system to build the +module if a binary wheel is not used. Use the ``--binary-wheels`` option when +using ``charm build``. + Snap Tracks/Version ------------------- Due to the complexity of building reactive charms across multiple Python versions, the tool has been split into two tracks: -1. For charms targetting Ubuntu focal (20.04) or earlier: 2.x -2. For charms targetting Ubuntu jammy (22.04) or later: 3.x +1. The 2.x track is hard coded to build using Python 3.6, which is the + equivalent of using Ubuntu 18.04 (Bionic) as a base. +2. The 3.x track uses the Python version from the build environement. This + means that it is useful for building charms from 20.04 onwards, but does + mean that a separate build (as indicated above) may need to be used for each + base the the charm should run on. Other charms.reactive projects ------------------------------