From 418bd0e33754bafd5515bfb0521801e7f77c4d3b Mon Sep 17 00:00:00 2001 From: Roger Binns Date: Tue, 19 Nov 2024 16:59:14 -0800 Subject: [PATCH] pyodide and packager docs Refs #534 --- doc/changes.rst | 10 ++++++ doc/install.rst | 84 ++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 93 insertions(+), 1 deletion(-) diff --git a/doc/changes.rst b/doc/changes.rst index b3226664..ce400306 100644 --- a/doc/changes.rst +++ b/doc/changes.rst @@ -10,6 +10,16 @@ history `__. APSW changes by version ----------------------- +next +==== + +Documentation on how to :ref:`build for pyodide `, the Python +WASM implementation that runs in the browser and NPM. PyPI does not +accept pyodide packages yet. + +Documentation on how to :ref:`build for packagers ` such as +those maintaining Linux and BSD distributions. + 3.47.0.0 ======== diff --git a/doc/install.rst b/doc/install.rst index 00ef7c47..bb0307a1 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -84,7 +84,7 @@ edit the :file:`setup.apsw` file inside. `__ (Source, includes this HTML Help) -* `apsw-3.47.0.0.cosign-bundle +* `apsw-3.47.0.0.cosign-bundle `__ cosign signature @@ -293,6 +293,88 @@ This performs the compilation of the C code, and provides more control than buil - Excludes old non :pep:`8` :ref:`complaint name aliases ` from the extension and type stubs. +.. _pyodide: + +Pyodide +------- + +`Pyodide `__ is web assembly +Python distribution that can run in the browser or via NPM. PyPI does not +support pyodide packages yet, but you can compile your own on a Linux +host. + +You should first download the source distribution listed at the top of +https://pypi.org/project/apsw/#files - the filename ends up being +``apsw-3.47.0.0.tar.gz`` in this example. The `cibuildwheel +`__ tool is used for the building, and +is the same tool used for the PyPI builds of APSW. + +.. code-block:: shell + + # Start out with a clean virtual environment + $ python3 -m venv venv + # Get cibuildwheel + $ venv/bin/pip3 install cibuildwheel + # Do the building which will download the necessary compiler and + # Python parts + $ venv/bin/cibuildwheel --platform pyodide apsw-3.47.0.0.tar.gz + # When it has finished the result is in the wheelhouse directory + $ ls wheelhouse/ + +You will then be able to install the wheel using `micropip +`__. + +.. code-block:: pycon + + >>> import micropip + >>> await micropip.install("https://url/apsw-3.47.0.0-cp312-cp312-pyodide_2024_0_wasm32.whl") + >>> import apsw + +At this point you will be able to use APSW as normal. + +.. _packagers: + +Advice for packagers +-------------------- + +This is the recommendation for packagers such as Linux and BSD, who +want APSW to use the system shared library. + +* Use the source file from `github releases + `__. Note you should + use the zip file including the version number, not the github + repository copy at the end. The file is signed and :ref:`can be + verified `. + + The file also includes a copy of the built documentation with no + analytics, but does include fonts from the documentation theme + provider. + +* After extracting the zip, create a file named ``setup.apsw`` that + sits alongside ``setup.py`` with the following contents: + + .. code-block:: ini + + [build_ext] + use_system_sqlite_config = True + + This will probe the system SQLite shared library for its compilation + options. Various C level APIs are included or excluded from the shared + library based on those options, so APSW needs to know at compilation + time which APIs it can or can't call. + +You can compile APSW using whatever works for your packaging system. +APSW complies with the latest Python packaging guidelines and +metadata. Ensure the ``setup.apsw`` is found during compilation +especially if files get copied to another directory. You will see lines like the +following (note the ``Extracting configuration``). + +.. code-block:: console + + running build_ext + Extracting configuration from libsqlite3.so.0 + SQLite: Using system sqlite include/libraries + .. _testing: Testing