From c9f41f9d90ab3cc2d2f5aa1a453450ecf3e77ed9 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Thu, 6 Feb 2025 17:32:39 -0500 Subject: [PATCH] explain more steps of the release process related to building packages --- .github/release_steps.md | 178 +++++++++++++++++++--- tools/singularity/README.md | 2 +- tools/singularity/fedora41_musl_mingw.def | 109 +++++++++++++ 3 files changed, 264 insertions(+), 25 deletions(-) create mode 100644 tools/singularity/fedora41_musl_mingw.def diff --git a/.github/release_steps.md b/.github/release_steps.md index 01b9224114..857acfdb85 100644 --- a/.github/release_steps.md +++ b/.github/release_steps.md @@ -35,7 +35,7 @@ document, last minute trivial(!) changes). This PR shall not be merged before **all** pending tests have completed and cleared. We currently use a mix of automated tests running on either Temple's Jenkins cluster or GitHub workflows. Those include time -consuming tests not run on pull requests. If needed, a bugfix pull +consuming tests not run on pull requests. If needed, a bug-fix pull request should be created and merged to clear all tests. ### Create release on GitHub @@ -56,7 +56,7 @@ git pull git checkout release git pull git merge --ff-only develop -git tag -s -m "LAMMPS feature release 19 November 2024" patch_19Nov2024 +git tag -s -m "LAMMPS feature release 4 February 2025" patch_4Feb2025 git push git@github.com:lammps/lammps.git --tags develop release ``` @@ -77,7 +77,7 @@ release page with a summary of all the changes included and references to the pull requests they were merged from or check the existing draft for any necessary changes from pull requests that were merged but are not listed. Then select the applied tag for the release in the "Choose -a tag" dropdown list. Go to the bottom of the list and select the "Set +a tag" drop-down list. Go to the bottom of the list and select the "Set as pre-release" checkbox. The "Set as the latest release" button is reserved for stable releases and updates to them. @@ -87,12 +87,18 @@ you can return to edit the release page and publish it. ### Prepare pre-compiled packages, update packages to GitHub -Build a fully static LAMMPS installation using a musl-libc -cross-compiler, install into a lammps-static folder, and create a -tarball called lammps-linux-x86_64-19Nov2024.tar.gz (or using a -corresponding date with a future release) from the lammps-static folder. A suitable build environment is provided with the -https://download.lammps.org/static/fedora37_musl.sif container image. +https://download.lammps.org/static/fedora41_musl_mingw.sif container +image. The corresponding container build definition file is maintained +in the tools/singularity folder of the LAMMPS source distribution. + +#### Fully portable static Linux x86_64 non-MPI binaries + +The following commands use the Fedora container to build a fully static +LAMMPS installation using a musl-libc cross-compiler, install it into a +`lammps-static` folder, and create a tarball called +`lammps-linux-x86_64-4Feb2025.tar.gz` (or using a corresponding date +with a future release) from the `lammps-static` folder. ``` sh rm -rf release-packages @@ -105,49 +111,173 @@ cmake -S lammps-release/cmake -B build-release -G Ninja -D CMAKE_INSTALL_PREFIX= cmake --build build-release --target all cmake --build build-release --target install /usr/musl/bin/x86_64-linux-musl-strip lammps-static/bin/* -tar -czvvf lammps-linux-x86_64-19Nov2024.tar.gz lammps-static +tar -czvvf ../lammps-linux-x86_64-4Feb2025.tar.gz lammps-static exit # fedora 41 container +cd .. ``` The resulting tar archive can be uploaded to the GitHub release page with: -``` -gh release upload patch_19Nov2024 lammps-linux-x86_64-19Nov2024.tar.gz +``` sh +gh release upload patch_4Feb2025 lammps-linux-x86_64-4Feb2025.tar.gz ``` +#### Linux x86_64 Flatpak bundle with GUI included + Make sure you have the `flatpak` and `flatpak-builder` packages -installed locally (they cannot be used from the container) and build a +installed locally (they require binaries that run with elevated +privileges and thus cannot be used from the container) and build a LAMMPS and LAMMPS-GUI flatpak bundle in the `release-packages` folder with: ``` sh +cd release-packages flatpak --user remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo flatpak-builder --force-clean --verbose --repo=$PWD/flatpak-repo --install-deps-from=flathub --state-dir=$PWD --user --ccache --default-branch=release flatpak-build lammps-release/tools/lammps-gui/org.lammps.lammps-gui.yml -flatpak build-bundle --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo --verbose $PWD/flatpak-repo LAMMPS-Linux-x86_64-GUI-19Nov2024.flatpak org.lammps.lammps-gui release +flatpak build-bundle --runtime-repo=https://flathub.org/repo/flathub.flatpakrepo --verbose $PWD/flatpak-repo ../LAMMPS-Linux-x86_64-GUI-4Feb2025.flatpak org.lammps.lammps-gui release +cd .. ``` The resulting flatpak bundle file can be uploaded to the GitHub release page with: -``` -gh release upload patch_19Nov2024 LAMMPS-Linux-x86_64-GUI-19Nov2024.flatpak +``` sh +gh release upload patch_4Feb2025 LAMMPS-Linux-x86_64-GUI-4Feb2025.flatpak ``` -Also build serial executable packages that also include LAMMPS-GUI for -Linux, macOS, and Windows, and upload them to the GitHub release. +#### LAMMPS Source tarball -Clean up: +The container for the static binary can also be used to prepare the source +tarball including the HTML and PDF manual (this is currently done automatically +when the releases is created and the tarball uploaded to https://download.lammps.org/tars/). +The steps are as follows: + +``` sh +cd release-packages +apptainer shell fedora41_musl_mingw.sif +cd lammps-release +rm -f ../release.tar* +git archive --output=../release.tar --prefix=lammps-4Feb2025/ HEAD +cd doc +make clean-all +make html pdf +tar -rf ../../release.tar --transform 's,^,lammps-4Feb2025/doc/,' html Manual.pdf +gzip -9v ../../release.tar +mv ../../release.tar.gz ../../lammps-src-4Feb2025.tar.gz +exit # fedora41 container +cd .. +``` + +The resulting source tarball can be uploaded to the GitHub release page with: + +``` sh +gh release upload patch_4Feb2025 lammps-src-4Feb2025.tar.gz +``` + +#### Build Windows Installer Packages with MinGW Linux-to-Windows Cross-compiler + +The various Windows installer packages can also be built with +apptainer container image. + +``` sh +cd release-packages +apptainer shell fedora41_musl_mingw.sif +git clone --depth 10 https://github.com/lammps/lammps-packages.git lammps-packages +cd lammps-packages/mingw-cross +ln -sf ../../lammps-release lammps +./buildall.sh release >& mk.log & less +F mk.log +``` + +The installer with the GUI included can be uploaded to the GitHub release page with: + +``` sh +ln -sf LAMMPS-64bit-GUI-4Feb2025.exe LAMMPS-Win10-64bit-GUI-4Feb2025.exe +gh release upload patch_4Feb2025 LAMMPS-Win10-64bit-GUI-4Feb2025.exe +``` + +The symbolic link is used to have a consistent naming scheme for the packages +attached to the GitHub release page. + +#### Clean up: ``` sh cd .. rm -r release-packages ``` -TODO: -- add detailed commands for building GUI packages on Ubuntu 20.04LTS (move to 22.04LTS?), - macOS, and Windows cross-compiler and upload to GitHub -- build all Windows cross-compiled installer packages using lammps-packages repo +#### Build Multi-arch App-bundle for macOS -### Update download website +Building app-bundles for macOS is not as easily automated and portable +as some of the other steps. It requires a machine actually running +macOS. In that machine the Xcode compiler package needs to be +installed. This also includes tools for building and manipulating disk +images. This compiler supports building executables for both, the +x86_64 and the arm64 architectures. This requires building with CMake +and using the CMake settings: + +``` sh +-D CMAKE_OSX_ARCHITECTURES=arm64;x86_64 +-D CMAKE_OSX_DEPLOYMENT_TARGER=11.0 +``` + +This will add the compiler flags `-arch arm64 -arch x86_64 +-mmacosx-version-min=11.0` and thus produce object for both +architectures and support for macOS versions back to version 11 (aka Big +Sur). With these settings the following libraries should be compiled +and installed (e.g. to `$HOME/.local`) as static libraries only: +- libomp taken from the LLVM/Clang source distribution (to support OpenMP) +- jpeg +- zlib +- png +- Qt (for LAMMPS-GUI) + +When configuring LAMMPS the `cmake/presets/clang.cmake` should be used +and as many packages as possible enabled. For LAMMPS-GUI, MPI should be +disabled with `-D BUILD_MPI=OFF` and LAMMPS-GUI enabled with +`-D BUILD_LAMMPS_GUI=ON`. If the CMake configuration is successful, +settings for building a macOS app-bundle are enabled and with `cmake +--build build --target dmg` extra steps will be executed that will build +a macOS application installer image under the name +`LAMMPS_GUI-macOS-multiarch-4Feb2025.dmg` + +The application image can be uploaded to the GitHub release page with: + +``` sh +ln -sf LAMMPS_GUI-macOS-multiarch-4Feb2025.dmg LAMMPS-macOS-multiarch-GUI-4Feb2025.dmg +gh release upload patch_4Feb2025 LAMMPS-macOS-multiarch-GUI-4Feb2025.dmg +``` + +The symbolic link is used to have a consistent naming scheme for the packages +attached to the GitHub release page. + +We are currently building the application images on macOS 12 (aka Monterey). + +#### Build Linux x86_64 binary tarball on Ubuntu 20.04LTS + +While the flatpak Linux version uses portable runtime libraries provided +by the flatpak environment, we also build regular Linux executables that +use a wrapper script and matching shared libraries in a tarball. To be +compatible with many Linux distributions, one has to build this on a +very old Linux distribution, since most Linux system libraries are +usually backward compatible but not forward compatible. This is +currently done on an Ubuntu 20.04LTS system. Once LAMMPS moves to +require CMake 3.20 and C++17, we will have to move to Ubuntu 22.04LTS. +This installation (either on a real or a virtual machine) should have +the packages installed that are indicated in +`tools/singularity/ubuntu20.04.def` plus Qt version 5.x with development +headers, so that LAMMPS-GUI can be compiled. + +Also the building of the binary tarball and setup of the bundled +libraries and wrapper scripts is automated and can executed with `cmake +--build build --target tgz`. This should produce a file +`LAMMPS_GUI-Linux-amd64-4Feb2025.tar.gz` which can be uploaded to the +GitHub release page with: + +``` sh +ln -sf LAMMPS_GUI-Linux-amd64-4Feb2025.tar.gz LAMMPS-Linux-x86_64-GUI-4Feb2025.tar.gz +gh release upload patch_4Feb2025 LAMMPS-Linux-x86_64-GUI-4Feb2025.tar.gz +``` + +### Update download page on LAMMPS website Check out the LAMMPS website repo https://github.com/lammps/lammps-website.git and edit the file @@ -156,7 +286,7 @@ html` and review `html/download.html` Then add and commit to git and push the changes to GitHub. The Temple Jenkis cluster will automatically update https://www.lammps.org/download.html accordingly. -Notify Steve of the release so he can update `src/bug.txt` on the +Also notify Steve of the release so he can update `src/bug.txt` on the website from the available release notes. ## LAMMPS Stable Release diff --git a/tools/singularity/README.md b/tools/singularity/README.md index 4700dac6ec..8f0508b9f0 100644 --- a/tools/singularity/README.md +++ b/tools/singularity/README.md @@ -1,6 +1,6 @@ # Apptainer (aka Singularity) container definitions for compiling/testing LAMMPS -The *.def files in this folder can be used to build container images +The \*.def files in this folder can be used to build container images for [Apptainer](https://apptainer.org) (previously called [Singularity](https://sylabs.io)), suitable for compiling and testing LAMMPS on a variety of OS variants with support for most standard diff --git a/tools/singularity/fedora41_musl_mingw.def b/tools/singularity/fedora41_musl_mingw.def new file mode 100644 index 0000000000..7e15f6590b --- /dev/null +++ b/tools/singularity/fedora41_musl_mingw.def @@ -0,0 +1,109 @@ +BootStrap: docker +From: fedora:41 + +%setup + curl -L -o musl-gcc-f37.tar.gz https://download.lammps.org/static/musl-gcc-f37.tar.gz + cp musl-gcc-f37.tar.gz ${APPTAINER_ROOTFS} + +%post + dnf -y update + dnf -y install vim-enhanced git file make cmake patch which file \ + ninja-build libomp-devel diffutils dos2unix findutils rsync \ + ccache gcc-c++ gcc-gfortran gdb valgrind python3-pyyaml \ + enchant enchant2 python3-enchant python3-virtualenv doxygen latexmk \ + texlive-latex-fonts texlive-pslatex texlive-collection-latexrecommended \ + texlive-latex texlive-latexconfig doxygen-latex texlive-collection-latex \ + texlive-latex-bin texlive-lualatex-math texlive-fncychap texlive-tabulary \ + texlive-framed texlive-wrapfig texlive-upquote texlive-capt-of texlive-pict2e \ + texlive-needspace texlive-titlesec texlive-anysize texlive-dvipng texlive-xindy \ + texlive-fontawesome texlive-ellipse texlive-tex-gyre \ + mingw-filesystem-base mingw32-nsis mingw-binutils-generic \ + mingw64-filesystem mingw64-pkg-config \ + mingw64-crt mingw64-headers mingw64-binutils \ + mingw64-cpp mingw64-gcc mingw64-gcc-gfortran mingw64-gcc-c++ \ + mingw64-curl \ + mingw64-libgomp \ + mingw64-winpthreads \ + mingw64-eigen3 \ + mingw64-fftw \ + mingw64-libjpeg-turbo \ + mingw64-libpng \ + mingw64-python3 \ + mingw64-python3-numpy \ + mingw64-python3-pyyaml \ + mingw64-python3-setuptools \ + mingw64-readline \ + mingw64-termcap \ + mingw64-tcl \ + mingw64-tk \ + mingw64-zlib \ + mingw64-zstd \ + mingw64-qt5-qtdeclarative \ + mingw64-qt5-qmldevtools \ + mingw64-qt5-qmldevtools-devel \ + mingw64-qt5-qttools-tools \ + mingw64-qt5-qtcharts \ + mingw64-qt5-qttools \ + mingw64-qt5-qmake \ + mingw64-qt5-qtbase \ + mingw64-qt5-qtbase-devel \ + mingw64-qt5-qtbase-static \ + + dnf clean all + + # install musl-libc Linux-2-Linux cross-compiler + tar -C /usr/ -xvf /musl-gcc-f37.tar.gz + rm -f /musl-gcc-f37.tar.gz + + # install NSIS EnVar plugin + curl -L -o EnVar_plugin.zip https://nsis.sourceforge.io/mediawiki/images/7/7f/EnVar_plugin.zip + unzip -d /usr/share/nsis EnVar_plugin.zip + rm EnVar_plugin.zip + + # create missing termcap pkgconfig file + cat > /usr/x86_64-w64-mingw32/sys-root/mingw/lib/pkgconfig/termcap.pc <$CUSTOM_PROMPT_ENV <