Tutorial: setuptools_scm

Tutorial: setuptools_scm#

Warning

This tutorial is in a draft outline state. It is provided as reference and will be fleshed out in future releases. Be sure to check back in on this tutorial or watch the Changelog for updates!

For the reproducible version number, it is beneficial to use a versioning scheme that includes information from the project’s version control system, e.g. git. The WAVES project uses git and setuptools_scm [55] to build version numbers with a clean version number that is uniquely tied to a single commit, e.g. 1.2.3, or a version number appended with the short git hash to uniquely identify the project commit.

References#

Environment#

SCons and WAVES can be installed in a Conda environment with the Conda package manager. See the Conda installation and Conda environment management documentation for more details about using Conda.

Note

The SALib and numpy versions may not need to be this strict for most tutorials. However, Tutorial: Sensitivity Study uncovered some undocumented SALib version sensitivity to numpy surrounding the numpy v2 rollout.

  1. Create the tutorials environment if it doesn’t exist

    $ conda create --name waves-tutorial-env --channel conda-forge waves 'scons>=4.6' matplotlib pandas pyyaml xarray seaborn 'numpy>=2' 'salib>=1.5.1' pytest

  2. Activate the environment

    $ conda activate waves-tutorial-env

Some tutorials require additional third-party software that is not available for the Conda package manager. This software must be installed separately and either made available to SConstruct by modifying your system’s PATH or by modifying the SConstruct search paths provided to the waves.scons_extensions.add_program() method.

Directory Structure#

  1. Create and change to a new project root directory to house the tutorial files if you have not already done so. For example

$ mkdir -p ~/waves-tutorials
$ cd ~/waves-tutorials
$ pwd
/home/roppenheimer/waves-tutorials

Note

If you skipped any of the previous tutorials, run the following commands to create a copy of the necessary tutorial files.

$ pwd
/home/roppenheimer/waves-tutorials
$ waves fetch --overwrite --tutorial 12 && mv tutorial_12_archival_SConstruct SConstruct
WAVES fetch
Destination directory: '/home/roppenheimer/waves-tutorials'

  1. Download the tutorial_12_archival file with the WAVES Command-Line Utility fetch subcommand. The SConscript file tutorial_12_archival does not need to change because we are already using the project configuration env["version"] in the archive file name.

$ pwd
/home/roppenheimer/waves-tutorials
$ waves fetch --overwrite tutorials/tutorial_12_archival
WAVES fetch
Destination directory: '/home/roppenheimer/waves-tutorials'

setuptools_scm configuration#

  1. Create a file named pyproject.toml using the contents below.

waves-tutorials/pyproject.toml

1[tool.pytest.ini_options]

SConstruct#

A diff against the SConstruct file from Tutorial 12: Data Archival is included below to help identify the changes made in this tutorial.

waves-tutorials/SConstruct

--- /home/runner/work/waves/waves/build/docs/tutorials_tutorial_12_archival_SConstruct
+++ /home/runner/work/waves/waves/build/docs/tutorials_tutorial_setuptools_scm_SConstruct
@@ -5,6 +5,7 @@
 import pathlib
 import inspect
 
+import setuptools_scm
 import waves
 
 # Comments used in tutorial code snippets: marker-1
@@ -61,6 +62,7 @@
     print_build_failures=GetOption("print_build_failures"),
     abaqus_commands=GetOption("abaqus_command"),
     TARFLAGS="-c -j",
+    TARSUFFIX=".tar.bz2",
 )
 
 # Conditionally print failed task *.stdout files
@@ -77,7 +79,7 @@
 
 # Set project internal variables and variable substitution dictionaries
 project_name = "WAVES-TUTORIAL"
-version = "0.1.0"
+version = setuptools_scm.get_version()
 archive_prefix = f"{project_name}-{version}"
 project_configuration = pathlib.Path(inspect.getfile(lambda: None))
 project_dir = project_configuration.parent

Version control system#

  1. Initialize a git repository in the tutorial directory

$ pwd
/home/roppenheimer/waves-tutorials
$ git init

  1. Put the current tutorial’s files under version control

$ pwd
/home/roppenheimer/waves-tutorials
$ git add SConstruct pyproject.toml tutorial_12_archival
$ git commit -m "Initial commit for git tag version numbers using setuptools_scm"
<output truncated>

  1. Create a git tag version number

$ pwd
/home/roppenheimer/waves-tutorials
$ git tag 0.1.0

  1. Verify that setuptools_scm is correctly picking up the git tag for the version number

$ pwd
/home/roppenheimer/waves-tutorials
$ python -m setuptools_scm
0.1.0

Build Targets#

  1. Build (or re-build) the archive target from Tutorial 12: Data Archival.

$ pwd
/home/roppenheimer/waves-tutorials
$ scons tutorial_12_archival_archive --jobs=4
<output truncated>

Output Files#

The output should look identical to Tutorial 12: Data Archival with the exception that the archive *.tar.bz2 file may contain version information relating to the git short commit hash. One side effect of the dynamic version number is that the archive task will always re-run when changes are made to the project repository, including any uncommitted changes to tracked files.

$ pwd
/home/roppenheimer/waves-tutorials
$ find build -name "*.tar.bz2"
build/tutorial_12_archival/WAVES-TUTORIAL-0.1.0.tar.bz2

To explore the dynamic version number, you can add new git commits. For instance, you might add a .gitignore file from the contents below

waves-tutorials/.gitignore

 1# Project files
 2build*/
 3*.tar.bz2
 4
 5# SCons files
 6.sconsign.dblite
 7config.log
 8
 9# Binary image files
10*.png
11*.jpg
12*.pdf
13
14# Abaqus output files
15*.com
16*.dat
17*.msg
18*.odb
19*.prt
20*.sim
21*.sta
22*.rpy*
23*.cae
24*.jnl
25
26# Cubit output file
27*.cub
28
29# Sphinx/Python
30__pycache__/
31*.pyc

  1. Place the .gitignore file under version control

$ pwd
/home/roppenheimer/waves-tutorials
$ git add .gitignore
$ git commit -m "MAINT: Ignore build artifacts"
[main ad02fc7] MAINT: Ignore build artifacts
 1 file changed, 33 insertions(+)
 create mode 100644 .gitignore

  1. Observe the dynamic version number change. The git short hash, ad02fc7, will differ for every user and is specific to your git repository.

$ pwd
/home/roppenheimer/waves-tutorials
$ python -m setuptools_scm
0.1.0.dev1+gad02fc7

Note

The leading g before the short hash ad02fc7 is not part of the hash. setuptools_scm can work with several version control systems and uses the leading g to indicate that this is a git repository.

  1. Re-build the archive target and note the archive file name change to match the version number from the previous step

$ pwd
/home/roppenheimer/waves-tutorials
$ scons tutorial_12_archival_archive --jobs=4
<output truncated>
$ find build -name "*.tar.bz2"
build/tutorial_12_archival/WAVES-TUTORIAL-0.1.0.tar.bz2
build/tutorial_12_archival/WAVES-TUTORIAL-0.1.0.dev1+gad02fc7.tar.bz2
Contents