diff --git a/.github/workflows/build-documentation.yml b/.github/workflows/build-documentation.yml index 7387dda..a7ed5f9 100644 --- a/.github/workflows/build-documentation.yml +++ b/.github/workflows/build-documentation.yml @@ -4,7 +4,7 @@ name: publish docs on: push: - branches: [ "trunk", "develop" ] + branches: [ "trunk" ] permissions: contents: read diff --git a/CMakeLists.txt b/CMakeLists.txt index cf6cc6f..6c3f18b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -80,16 +80,8 @@ else() endif() # When CCP4 is sourced in the environment, we can recreate the symmetry operations table -if(EXISTS "$ENV{CCP4}") - if(EXISTS "$ENV{CCP4}/lib/data/syminfo.lib") - option(CIFPP_RECREATE_SYMOP_DATA "Recreate SymOp data table in case it is out of date" ON) - else() - set(CIFPP_RECREATE_SYMOP_DATA OFF) - message(WARNING "Symop data table recreation requested, but file syminfo.lib was not found in $ENV{CLIBD}") - endif() -else() - set(CIFPP_RECREATE_SYMOP_DATA OFF) - message("Not trying to recreate symop_table_data.hpp since CCP4 is not defined") +if(EXISTS "$ENV{CCP4}/lib/data/syminfo.lib") + option(CIFPP_RECREATE_SYMOP_DATA "Recreate SymOp data table in case it is out of date" ON) endif() # CCP4 build diff --git a/README.md b/README.md index 6b90adc..ddd0f7c 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,28 @@ # libcifpp -This library contains code to work with mmCIF and legacy PDB files. +As the name implies, this library was originally written to work with mmCIF files +using C++ as programming language. The design of this library leanes heavily on +the structure of CIF files. These files can be thought of as a text dump of a +relational databank with, often but not always, a very strict schema describing +the data. These schema's are called dictionaries. + +Using information from the content of a mmCIF file and an optional schema, +libcifpp allows you to access the data in the file as a collection of datablock +each containing a collection of categories with rows of data. The categories can +be searched for data using queries written in regular C++ syntax. When a dictionary +was specified, inserted data is checked for validity. Likewise removal of data +may result in cascaded removal of linked data in other categories using +parent/child relationship information. + +Since there were still many programs using the legacy PDB format at the time +development started, a layer was added that converts data to and from PDB format +into mmCIF format. This means you can manipulate PDB files as if they were +normal mmCIF files. + +Apart from this basic functionality, libcifpp also offers code to help with +symmetry calculations, 3d manipulations and obtaining information from the CCD +[Chemical Component Dictionary](https://www.wwpdb.org/data/ccd). ## Documentation @@ -67,54 +88,138 @@ int main(int argc, char *argv[]) You might be able to use libcifpp from a package manager used by your OS distribution. But most likely this package will be out-of-date. Therefore it is recommended to build *libcifpp* from code. It is not -hard to do. +hard to do. But it is recommended to read the following instructions +carefully. ### Requirements The code for this library was written in C++17. You therefore need a -recent compiler to build it. For the development gcc 9.4 and clang 9.0 +recent compiler to build it. For the development gcc >= 9.4 and clang >= 9.0 have been used as well as MSVC version 2019. -Other requirements are: +The other requirement you really need to have installed on your computer +is a version of [CMake](https://cmake.org). For now the minimum version +is 3.16 but that may soon change into a higher version. You should also +install the gui version of CMake to set build options easily, on Debian +I prefer to use the curses version installed with `cmake-curses-gui`. + +It is very useful to have [mrc](https://github.com/mhekkel/mrc) available. +However, this is only an option if you use Windows or an operating system +using the ELF executable format (i.e. Linux or FreeBSD). MRC is a resource +compiler that allows including data files into the executable making them +easier to install. + +Other libraries you might want to install beforehand are: -- [cmake](https://cmake.org) A build tool. -- [mrc](https://github.com/mhekkel/mrc), a resource compiler that - allows including data files into the executable making them easier to - install. Strictly speaking this is optional, but at the expense of - functionality. - [libeigen](https://eigen.tuxfamily.org/index.php?title=Main_Page), a library to do amongst others matrix calculations. This usually can be installed using your package manager, in Debian/Ubuntu it is called `libeigen3-dev` - [zlib](https://github.com/madler/zlib), the development version of this library. On Debian/Ubuntu this is the package `zlib1g-dev`. -- [boost](https://www.boost.org). - -The Boost libraries are only needed in case you want to build the test -code or if you are using GCC. That last condition is due to a long -standing bug in the implementation of std::regex. It simply crashes -on the regular expressions used in the mmcif_pdbx dictionary and so -we use the boost regex implementation instead. +- [boost](https://www.boost.org), in Debian/Ubuntu this is `libboost-dev`. + + The Boost libraries are only needed in case you are using GCC due to a long + standing bug in GNU's implementation of std::regex. It simply crashes + on the regular expressions used in the mmcif_pdbx dictionary and so + we use the boost regex implementation instead. ### Building -Building the code is as simple as typing: +First you need to download the code: ```console - git clone https://github.com/PDB-REDO/libcifpp.git --recurse-submodules + git clone https://github.com/PDB-REDO/libcifpp.git cd libcifpp - cmake -S . -B build -DCMAKE_INSTALL_PREFIX=$HOME/.local -DCMAKE_BUILD_TYPE=Release - cmake --build build - cmake --install build ``` -This checks out the source code from github, creates a new directory -where cmake stores its files. Run a configure, build the code and then -it installs the library and auxiliary files. +You should start by considering where to install libcifpp. If you have +sufficient permissions on your computer you perhaps should use the +default but libcifpp can be configured to be installed anywhere +including e.g. *$HOME/.local*. + +Next step is to configure, for this use the CMake gui application. If you +installed the curses version of cmake you can type `ccmake`. On Windows +you can use `cmake-gui.exe`. + +To install in the default location: + +```console +ccmake -S . -B build +``` + +To install elsewhere, e.g. *$HOME/.local*: + +```console +ccmake -S . -B build -DCMAKE_INSTALL_PREFIX=$HOME/.local +``` + +In the cmake window, start the configure command (use button or press 'c'). +After the first configure step you will see a list of settable options. +Alter these to match your preferences. Most options are self explaining +and contain a description. Some may need a bit more explanation: + +- CIFPP_DATA_DIR, this directory will be used to store initial versions + of the mmcif_pdbx dictionary as well as the optional CCD file. + +- CIFPP_DOWNLOAD_CCD + + The CCD file is huge and perhaps you think you don't + need it. In that case you can leave this OFF. But that will limit the + use cases. + +- CIFPP_INSTALL_UPDATE_SCRIPT + + The files in CIFPP_DATA_DIR are quickly becoming out of date. On + FreeBSD and Linux you can install a script that updates these files + on a weekly basis. + +- CIFPP_CRON_DIR + + The directory where the update script is to be installed. + +- CIFPP_ETC_DIR + + The update script will only work if the file called *libcifpp.conf* + in this *etc* directory will contain an uncommented line with + +```console +update=true +``` + +- CIFPP_CACHE_DIR + + When you installed and enabled the update script, new files are + written to this directory. + +- CIFPP_RECREATE_SYMOP_DATA + + If you had CCP4 sourced into your environment, this option allows + you to recreate the symop data file. + +- BUILD_FOR_CCP4 + + Build a special version of libcifpp to be installed in the CCP4 + environment. + +After setting these options you can run the configure step again and +then use generate to create the makefiles. + +Building and installing is then as simple as: + +```console +cmake --build build +cmake --install build +``` + +If this fails due to lack of permissions, you can try: + +```console +sudo cmake --install build +``` Tests are created by default, and to test the code you can run: ```console - cmake --build build - ctest --test-dir build +ctest --test-dir build ```