Skip to main content
`Ctrl`+`K`

# 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 [60] 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

- setuptools_scm [60]

## 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

   Linux/MacOS

       $ 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

   Windows

       PS > conda create --name waves-tutorial-env --channel conda-forge waves scons matplotlib pandas pyyaml xarray seaborn numpy salib pytest

2. Activate the environment

   Linux/MacOS

       $ conda activate waves-tutorial-env

   Windows

       PS > 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

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

Linux/MacOS

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

Windows

    PS > New-Item $HOME\waves-tutorials -ItemType "Directory"
    PS > Set-Location $HOME\waves-tutorials
    PS > Get-Location

    Path
    ----
    C:\Users\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'

4. 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

5. 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

6. Initialize a git repository in the tutorial directory

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

7. 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>

8. Create a git tag version number

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

9. 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

10. 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

11. 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

12. 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.

13. 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