These instructions produce a 'native' build, and should work on either Linux or MacOS (MacOS compatibility is not as frequently tested however). For Linux, it is also possible to build a Flatpak package which can then be installed using the flatpak package manager, see here.
First, install all neccessary build dependencies:
- C compiler: gcc (or clang)
- GNU make
- SDL3, SDL3_image, SDL3_ttf
- SDL3 should be built with
libdecoron Linux when using GNOME Wayland, otherwise window decorations won't be present.
- SDL3 should be built with
- pkg-config
Some older Linux distros may not package SDL3 and its libraries since they are fairly recent, in that case you will have manually compile them.
In Arch Linux:
pacman -Syu base-devel sdl3 sdl3_image sdl3_ttf pkgconf
In MacOS:
First install Homebrew. Then:
brew install pkg-config sdl3 sdl3_image sdl3_ttf
Clone the source repo:
git clone https://github.com/e-j-w/ChartOfNuclides.git
cd ChartOfNuclides
Build the application binaries using make (from the source tree root directory):
# using gcc:
make all -j
# alternatively, using clang:
make all -j CC=clang
Two executables will be built: proc_data (which generates the data package containing the nuclear structure database used by the main application), and chart (the main application).
Build the data file, which is neccessary to run the application. Once it is built, the application can be run:
./chart
To install the application for all users, on a Linux system:
sudo make install-linux
To uninstall:
sudo make uninstall-linux
This will build a sandboxed Flatpak package, which can then be installed on any Linux machine which already has flatpak (this is the way the official releases are built). This is the recommended method for most users since the Flatpak builder should resolve all dependencies and download all neccessary data files, however the automatic build process can take some time. If you want to avoid that, you can do a manual build instead.
On Arch Linux:
sudo pacman -Syu flatpak git
On Debian/Ubuntu:
sudo apt install flatpak git
Setup flatpak with the Flathub repo and get the build metadata (from this repo):
flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo
sudo flatpak install -y flathub org.flatpak.Builder
git clone https://github.com/e-j-w/ChartOfNuclides-flatpak
cd ChartOfNuclides-flatpak
Build the application (if this command fails with a free disk space error, run ostree --repo=repo config set core.min-free-space-percent 0 and then try again):
flatpak run org.flatpak.Builder --force-clean --sandbox --user --install-deps-from=flathub --disable-rofiles-fuse --ccache --repo=repo flatpak_build io.github.e_j_w.ChartOfNuclides-master.yml
Then package the application into a single file bundle:
flatpak build-bundle repo ChartOfNuclides.flatpak io.github.e_j_w.ChartOfNuclides
The ChartOfNuclides.flatpak bundle produced here can be used to install the application on any Linux machine with flatpak. To install, run:
flatpak install ChartOfNuclides.flatpak
Clean up the build to save disk space (optional):
rm -rf flatpak_build .flatpak-builder repo
The "Chart of Nuclides" application should now be available in your application menu and/or via the application search interface (depending on your desktop environment). Or you can run the application directly from the terminal:
flatpak run io.github.e_j_w.ChartOfNuclides
To uninstall the application, run:
flatpak uninstall io.github.e_j_w.ChartOfNuclides
Have fun!
There are various guides online for building SDL3 programs in Windows. In a Windows 10 VM, the following has worked for me:
- Install mingw-w64 and SDL3 via MSYS2. Follow the installation instructions, and then run mingw-w64 (
MSYS2 MinGW UCRT x64in the Start Menu). Install mingw-w64 and the SDL3 libraries from the MSYS2 terminal:
pacman -S --needed base-devel pkgconf mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-sdl3 mingw-w64-ucrt-x86_64-sdl3-ttf mingw-w64-ucrt-x86_64-sdl3-image
Go to the source directory, and compile:
cd /c/path/to/ChartOfNuclides
make all -j
Build the data file (using the same procedure as on other operating systems).
Check which DLLs are needed to run the application by running ldd chart.exe. Copy all of the listed DLLs from the MSYS2 distribution to the same directory as chart.exe. Then, it should be possible to run chart.exe from the file manager.
In order for the application to run, it requires a data file (chart.dat) containing the nuclear structure database and graphics/font resources. The application will look for the data file in any of the following locations (in order of preference):
| Location Name | Path |
|---|---|
| User-specific data path | ~/.local/share/chart/ (Linux) |
| Executable directory | The same directory that the executable was run from. |
| System-wide data path | /usr/share/chart/ (Linux) |
If you don't have the chart.dat data file, it can be built from the original data files using the proc_data program (built during the previous step). First you must obtain the required data files:
| Data | Source location | Instructions |
|---|---|---|
| Nuclear structure data | ENSDF | Download the zip archive from the link in the 'Latest Dataset' section. Unzip it in the source tree into the directory data/ensdf/ (such that the ensdf subdirectory contains the files ensdf.001, ensdf.002, etc.). |
| Mass data | AME2020 | This data is already provided in this repo (at data/masses.txt). If you want to retreive/update the data yourself, go to the source website, then download the first ASCII file (mass_1.mas20). Save/rename this file at data/masses.txt. |
| Isotope abundance data | NIST | This data is already provided in this repo (at data/abundances.txt). If you want to retreive/update the data yourself, go to the source website, then under 'Search the Database', select 'All Elements', output type 'Linearized ASCII Output', with the option 'Most common isotopes'. Select 'Get Data'. Copy the resulting plaintext data into a text file, save the text file in the source tree under data/abundances.txt. |
Once the data files are properly set up, run:
./proc_data
This will build the data package file chart.dat in the same directory (you can then get rid of the original data files if you don't want them anymore).