diff --git a/Makefile.am b/Makefile.am index 7aa489f..71183c0 100644 --- a/Makefile.am +++ b/Makefile.am @@ -24,25 +24,24 @@ EXTRA_DIST = \ NEWS.md \ README.md \ configure.ac \ - docker/README \ - docker/README-developer \ + docker/README.md \ docker/builder.py \ docker/centos-7 \ docker/rockylinux-8 \ docker/debian-stable \ docker/debian-testing \ - docker/fedora-35 \ - docker/fedora-36 \ - docker/fedora-37 \ - docker/ubuntu-18.04 \ + docker/fedora-38 \ + docker/fedora-39 \ docker/ubuntu-20.04 \ docker/ubuntu-22.04 \ - docker/ubuntu-22.10 \ + docker/ubuntu-23.04 \ + docker/ubuntu-23.10 \ packager/build.py \ packager/setup_macos.sh \ packager/setup_linux.sh \ packager/build.py \ - packager/make_petscdist.sh + packager/make_petscdist.sh \ + packager/README.md dist_noinst_SCRIPTS = \ diff --git a/README.md b/README.md index 071fab7..b604b61 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ This installer builds the current PyLith release and its dependencies from sourc ## Documentation * [Development version](https://pylith-installer.readthedocs.io/en/latest/) -* [Stable version](heeps://pylith-installer.readthedocs.io/en/v3.0.3-0) +* [Stable version](heeps://pylith-installer.readthedocs.io/en/v4.0.0-0) * See the corresponding version of the PyLith manual for v2.2.2 and earlier ## Author diff --git a/developer/release-announcement.md b/developer/release-announcement.md index 4fa6dc8..06425ec 100644 --- a/developer/release-announcement.md +++ b/developer/release-announcement.md @@ -1,14 +1,13 @@ -We are pleased to announce release of PyLith Installer version 3.0.3-0. +We are pleased to announce release of PyLith Installer version 4.0.0-0. Please submit bug reports via GitHub issues: https://github.com/geodynamics/pylith_installer/issues -PyLith Installer is free software. See the file COPYING for copying -conditions. +PyLith Installer is free software. See the file LICENSE.md for licensing information. PyLith Installer is a utility for building PyLith and its dependencies from source on Unix flavored operating systems. You can download the installer from https://geodynamics.org/resources/pylith. -Instructions are online at https://pylith-installer.readthedocs.io/en/v3.0.3-0. +Instructions are online at https://pylith-installer.readthedocs.io/en/v4.0.0-0. diff --git a/docker/README-developer.md b/docker/README-developer.md deleted file mode 100644 index 1b359a6..0000000 --- a/docker/README-developer.md +++ /dev/null @@ -1,38 +0,0 @@ -# Building Docker containers - -This directory holds Docker container build instructions, aka Dockerfiles. -The images are stored in the geodynamics GitHub container registry with the URL `ghcr.io/geodynamics/pylith_installer`. - -To set the visibility of container images, go to `github.com/geodynamics` -> `packages` (tab) -> `settings` (right side); the visibility setting is near the bottom. - -## Containers - -- **pylith-devenv**: Linux developer environment for PyLith (contains only dependencies) -- **pylith-binaryenv**: Linux environment for creating Linux binary package -- **Test environments**: - - **centos-7**: EOL June 2024 - - **debian-stable**: - - **debian-testing**: - - **fedora-38**: - - **fedora-39**: - - **rockylinux-8**: - - **rockylinux-9**: - - **ubuntu-20.04**: LTS - - **ubuntu-22.04**: LTS - - **ubuntu-23.04**: - - **ubuntu-23.10*: - -## Building images - -```bash -cd $SRC -docker/build.py --dockerfile=docker/ubuntu-22.04 --build --build-env=certs-doi -``` - -## Push images - -```bash -# Linux -pass -c PATH_TO_TOKEN -docker push IMAGE_URL -``` diff --git a/docker/README.md b/docker/README.md index f9485b0..c1ba747 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,119 +1,38 @@ -What is Docker? - - From https://www.docker.com/what-docker: - - "Docker containers wrap a piece of software in a complete - filesystem that contains everything needed to run: code, runtime, - system tools, system libraries – anything that can be installed on - a server. This guarantees that the software will always run the - same, regardless of its environment. - - LIGHTWEIGHT - - Containers running on a single machine share the same operating - system kernel; they start instantly and use less RAM. Images are - constructed from layered filesystems and share common files, - making disk usage and image downloads much more efficient." - -====================================================================== -Setup (first time only) -====================================================================== - -Install Docker: https://www.docker.com/products/docker - -Create container to store persistent user data - - This container will hold a directory where all your user data can be - stored for use with PyLith within Docker. This directory is not - directly accessible from your host computer. However, you can copy - files to/from your host filesystem using "docker cp" (see below). - - $ docker create --name pylith-data geodynamics/pylith-data - - -====================================================================== -Run Unix shell within Docker to use PyLith. -====================================================================== - - $ docker run -ti --volumes-from pylith-data geodynamics/pylith - - To enable use of GUI applications, like iceweasel (Firefox), use - - Linux: - $ xhost +local:root - Darwin (using Terminal application): - $ xhost +YOUR_IP_ADDRESS; DISPLAY=YOUR_IP_ADDRESS:0 - For Linux and Darwin, then continue with - $ XSOCK=/tmp/.X11-unix - $ docker run -ti --volumes-from pylith-data -e DISPLAY=$DISPLAY -v $XSOCK:$XSOCK geodynamics/pylith - - The container includes the following useful utilities: - * iceweasel (Firefox) web-browser for use with pylith_paramviewer - * vim text editor - * matplotlib Python plotting package - - We do not yet include ParaView due to difficulties associated with - rendering on the host display outside the container. - -HINT: You will probably want to copy the examples from the - pylith-VERSION directory to the data directory, which is the - persistent storage. - - $ cp -R ~/pylith-VERSION/examples ~/data - - To "pause" the container. - Control-p Control-q - - To attach to "paused" or "running" container. - # Find the container id - $ docker ps - # Attach to the container - $ docker attach CONTAINER_ID - - To restart an existing container after it exited. - # Get the container id - $ docker ps -a - # Start and then attach to the container. - $ docker start CONTAINER_ID - $ docker attach CONTAINER_ID - - -====================================================================== -Copy data to/from persistent storage volume. -===================================================================== - -Copy data FROM persistent storage volume TO local host - $ docker cp pylith-data:/data/pylith-user/PATH/FILENAME LOCAL_PATH - -Copy data FROM local host TO persistent storage volume - $ docker cp LOCAL_PATH pylith-data:/data/pylith-user/PATH/ - - -====================================================================== -Docker Quick Reference -====================================================================== - - List local docker images - $ docker images - - List all docker containers - $ docker ps -a - - List running docker containers - $ docker ps - - Remove docker container - $ docker rm CONTAINER_ID - - Remove docker image - $ docker rmi CONTAINER_ID - - Attach to stopped container with a different command - $ docker ps -a - $ docker commit CONTAINERID debug_container - $ docker run -ti --entrypoint=bash $IMAGE -s - -====================================================================== -Running GUI -====================================================================== - +# Building Docker containers + +This directory holds Docker container build instructions, aka Dockerfiles. +The images are stored in the geodynamics GitHub container registry with the URL `ghcr.io/geodynamics/pylith_installer`. + +To set the visibility of container images, go to `github.com/geodynamics` -> `packages` (tab) -> `settings` (right side); the visibility setting is near the bottom. + +## Containers + +- **pylith-devenv**: Linux developer environment for PyLith (contains only dependencies) +- **pylith-binaryenv**: Linux environment for creating Linux binary package +- **Test environments**: + - **centos-7**: EOL June 2024 + - **debian-stable**: + - **debian-testing**: + - **fedora-38**: + - **fedora-39**: + - **rockylinux-8**: + - **rockylinux-9**: + - **ubuntu-20.04**: LTS + - **ubuntu-22.04**: LTS + - **ubuntu-23.04**: + - **ubuntu-23.10**: + +## Building images + +```bash +cd $SRC +docker/build.py --dockerfile=docker/ubuntu-22.04 --build --build-env=certs-doi +``` + +## Push images + +```bash +# Linux +pass -c PATH_TO_TOKEN +docker push IMAGE_URL +``` diff --git a/docs/conf.py b/docs/conf.py index 27bf516..0b76d2a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,7 +21,7 @@ author = 'Brad T. Aagaard' # The full version, including alpha/beta/rc tags -release = 'v3.0.3-1' +release = 'v4.0.0-0' # -- General configuration --------------------------------------------------- diff --git a/docs/configs/macos.md b/docs/configs/macos.md index 38cf699..be9202a 100644 --- a/docs/configs/macos.md +++ b/docs/configs/macos.md @@ -25,7 +25,7 @@ PREFIX=$HOME/pylith # Define PETSc options petsc_options="--download-chaco=1 --download-ml --download-f2cblaslapack --with-fc=0 --with-hwloc=0 --with-ssl=0 --with-x=0 --with-c2html=0 --with-lgrind=0" # -${HOME}/src/pylith/pylith_installer-3.0.3-0/configure \ +${HOME}/src/pylith/pylith_installer-4.0.0-0/configure \ --prefix=${PREFIX} \ --enable-force-install \ --with-fetch=curl \ diff --git a/docs/devenv/configs.md b/docs/devenv/configs.md index b7fc911..6164c39 100644 --- a/docs/devenv/configs.md +++ b/docs/devenv/configs.md @@ -52,7 +52,7 @@ We use the following directory structure: ```{code-block} console pylith-developer/ -├── pylith_installer-3.0.3-0 # source code for the installer +├── pylith_installer-4.0.0-0 # source code for the installer ├── build-debug # top-level directory for building with debugging └── pylith-debug # directory where PyLith and other CIG code is installed by installer ``` @@ -96,7 +96,7 @@ mkdir -p $PYLITH_DIR cd $PYLITH_DIR # Place the installer source code tarball in $PYLITH_DIR and then unpack the tarball. -tar -xf pylith_installer-3.0.3-0.tar.gz +tar -xf pylith_installer-4.0.0-0.tar.gz ``` ## Linux @@ -126,7 +126,7 @@ Configure the installer. ```{code-block} bash mkdir $PYLITH_DIR/build-debug cd $PYLITH_DIR/build-debug -$PYLITH_DIR/pylith_installer-3.0.3-0/configure \ +$PYLITH_DIR/pylith_installer-4.0.0-0/configure \ --enable-developer \ --with-debugging \ --with-pylith-git=$PYLITH_BRANCH \ @@ -182,7 +182,7 @@ Configure the installer. ```{code-block} bash mkdir $PYLITH_DIR/build-debug cd $PYLITH_DIR/build-debug -${HOME}/src/pylith/pylith_installer-3.0.3-0/configure \ +${HOME}/src/pylith/pylith_installer-4.0.0-0/configure \ --enable-developer \ --with-debugging \ --with-pylith-git=$PYLITH_BRANCH \ diff --git a/docs/devenv/docker/index.md b/docs/devenv/docker/index.md index a652e20..7ad497d 100644 --- a/docs/devenv/docker/index.md +++ b/docs/devenv/docker/index.md @@ -1,4 +1,18 @@ -# PyLith development environment Docker image +# PyLith development environment using Docker + +## What is Docker? + +From https://www.docker.com/what-docker: + +> "Docker containers wrap a piece of software in a complete filesystem that contains everything needed to run: code, runtime, system tools, system libraries – anything that can be installed on a server. +> This guarantees that the software will always run the same, regardless of its environment. +> +> LIGHTWEIGHT +> +> Containers running on a single machine share the same operating system kernel; they start instantly and use less RAM. +> Images are constructed from layered filesystems and share common files, making disk usage and image downloads much more efficient." + +# PyLith development Docker image The `pylith-devenv` Docker image provides all of the dependencies and defines the environment for PyLith development. It is built using the Ubuntu 22.04 Linux distribution. diff --git a/docs/devenv/docker/quickref.md b/docs/devenv/docker/quickref.md index 4cac8bd..b573e12 100644 --- a/docs/devenv/docker/quickref.md +++ b/docs/devenv/docker/quickref.md @@ -16,3 +16,29 @@ docker cp pylith-dev-workspace:/opt/pylith/src/myfile.txt . # Attach to running container `pylith-dev-workspace` as root docker exec -it -u root pylith-dev-workspace /bin/bash ``` + +## Docker images + +```{code-block} bash +# List local images +docker images + +# Remove docker image using id +docker rmi IMAGE_ID + +# Remove docker image using tag +docker rmi IMAGE_TAG +``` + +## Docker containers + +```{code-block} bash +# List all docker containers +docker ps -a + +# List running docker containers +docker ps + +# Remove docker container +docker rm CONTAINER_ID +``` diff --git a/docs/devenv/docker/update.md b/docs/devenv/docker/update.md index fdc5ca8..d88b560 100644 --- a/docs/devenv/docker/update.md +++ b/docs/devenv/docker/update.md @@ -15,4 +15,4 @@ Pulling the PyLith development environment Docker image does not update Pythia, ## Updating PETSc or PyLith -See [Rebuilding PETSc and PyLith in the PyLith Developer Guide](https://pylith.readthedocs.io/en/v3.0.3/developer/contributing/rebuilding.html) for how to update PETSc and PyLith. +See [Rebuilding PETSc and PyLith in the PyLith Developer Guide](https://pylith.readthedocs.io/en/v4.0.0/developer/contributing/rebuilding.html) for how to update PETSc and PyLith. diff --git a/packager/README.md b/packager/README.md index d0e56b5..d105229 100644 --- a/packager/README.md +++ b/packager/README.md @@ -1,9 +1,10 @@ +# Binary packaging + Binary version is distributed via tarballs that are generated using the build.py script. `export SSL_CERT_FILE="$CERT_PATH/$CERT_FILE" REQUESTS_CA_BUNDLE="$CERT_PATH/$CERT_FILE"` - ## Linux 1. `docker volume create pylith-binary` @@ -21,4 +22,4 @@ the build.py script. 1. `cd ~/scratch/build/pylith-binary` 2. `mkdir src && pushd src && ln -s $HOME/src/pylith_installer && popd` 3. x86_64: `src/pylith_installer/packager/build.py --base-dir=`pwd` --make-threads=8 --macos-target=10.15 --setup` -3. arm64: `src/pylith_installer/packager/build.py --base-dir=`pwd` --make-threads=32 --macos-target=11.0 --setup` +4. arm64: `src/pylith_installer/packager/build.py --base-dir=`pwd` --make-threads=32 --macos-target=11.0 --setup`