From 08d67fa36a32f80ce19feb157fac23e978f6f716 Mon Sep 17 00:00:00 2001 From: Goran Jelic-Cizmek Date: Wed, 6 Mar 2024 09:38:37 +0100 Subject: [PATCH] Update docs --- INSTALL.rst | 2 ++ packaging/README.rst | 72 +++++++++++++++++++++++--------------------- 2 files changed, 39 insertions(+), 35 deletions(-) diff --git a/INSTALL.rst b/INSTALL.rst index 9c4fc6af4..65bf1e2ca 100644 --- a/INSTALL.rst +++ b/INSTALL.rst @@ -180,6 +180,8 @@ libpywrapper two environment variables need to be present: building without linking against libpython we must set ``NMODL_PYLIB`` before running cmake! +.. _testing-installed-module: + Testing the Installed Module ---------------------------- diff --git a/packaging/README.rst b/packaging/README.rst index eb2d8ddf7..f4cc83cff 100644 --- a/packaging/README.rst +++ b/packaging/README.rst @@ -4,8 +4,8 @@ Building Python Wheels Note: This is only slightly adapted from NEURONs `scripts `__. -NMODL wheels are built in a manylinux2010 image. Since the generic -docker image is very basic (CentOS 6) a new image, which brings updated +NMODL wheels are built in a manylinux2014 image. Since the generic +docker image is very basic (CentOS 7), a new image, which brings updated cmake3 (3.12), flex and bison was prepared and made available at https://hub.docker.com/r/bluebrain/nmodl (tag: wheel). @@ -18,7 +18,7 @@ Linux `here `__ and on OS X `here `__. On Ubuntu system we typically do: -:: +.. code::sh sudo apt install docker.io sudo groupadd docker @@ -26,56 +26,58 @@ Ubuntu system we typically do: Logout and log back in to have docker service properly configured. -Pull and start the docker image -------------------------------- +Launch the wheel building +------------------------- -We mount local neuron repository inside docker as a volume to preserve -any code changed. We can use -v option to mount the local folder as: +For building the wheel we use the ``cibuilwwheel`` utility, which can be installed using: -:: +.. code::sh - docker run -v /home/user/nmodl:/root/nmodl -it bluebrain/nmodl:wheel bash + pip install cibuildwheel -where ``/home/user/nmodl`` is the NMODL repository on the host machine. -We mount this directory inside docker at location ``/root/nmodl`` inside -the container. +Then to build a wheel for the current platform, run: -Note that for OS X there is no docker image but on a system where all -dependencies exist, you have to perform next building step. +.. code::sh -Launch the wheel building -------------------------- + cibuildwheel -Once we are inside docker container, we can start building wheels. There -is a build script that loops over the pythons ``>=3.5`` in -``/opt/python``, build and audit the generated wheels. Results are -placed in this wheelhouse directory. +If you have Docker installed, you can also build the Linux wheels using: -:: +.. code::sh - cd /root/nmodl - bash packaging/python/build_wheels.bash linux + cibuildwheel --platform linux -For OSX on a system with the all dependencies you have to clone the -NMODL repository and do: +Note that, if you happen to have Podman installed instead of Docker, you can +set ``CIBW_CONTAINER_ENGINE=podman`` to use Podman instead of Docker for this +task. -:: +Furthermore, in order to build wheels on MacOS, you need to install an official +CPython installer from `python.org `__. - cd nrn - bash packaging/python/build_wheels.bash osx +For a complete list of all available customization options for +``cibuildwheel``, please consult the +`documentation `__. -Updating neuron_wheel docker image ----------------------------------- +Testing the wheel +----------------- + +On MacOS, the testing of the wheel is launched automatically when running +``cibuildwheel``. On Linux, you will need to test the wheel manually, please +see :ref:`testing-installed-module` for the instructions. + + +Updating the NMODL Docker image +------------------------------- -If you have changed Dockerfile, you can build the new image as: +If you have changed the Dockerfile, you can build the new image as: -:: +.. code::sh docker build -t bluebrain/nmodl:tag . -and then push image to hub.docker.com as: +and then push the image to hub.docker.com as: -:: +.. code::sh docker login --username= - docker push bluebrain/nmodl:tag + docker push bluebrain/nmodl:tag