psdi-data-conversion 0.0.35__py3-none-any.whl → 0.0.37__py3-none-any.whl

psdi_data_conversion/testing/utils.py

@@ -19,19 +19,55 @@ from unittest.mock import patch
 import py
 import pytest
 
+import psdi_data_conversion
 from psdi_data_conversion.constants import CONVERTER_DEFAULT, GLOBAL_LOG_FILENAME, LOG_NONE, OUTPUT_LOG_EXT
 from psdi_data_conversion.converter import run_converter
 from psdi_data_conversion.converters.openbabel import COORD_GEN_KEY, COORD_GEN_QUAL_KEY
 from psdi_data_conversion.dist import LINUX_LABEL, get_dist
 from psdi_data_conversion.file_io import is_archive, split_archive_ext
 from psdi_data_conversion.main import main as data_convert_main
-from psdi_data_conversion.testing.constants import INPUT_TEST_DATA_LOC
+from psdi_data_conversion.testing.constants import (INPUT_TEST_DATA_LOC_IN_PROJECT, OUTPUT_TEST_DATA_LOC_IN_PROJECT,
+                                                    TEST_DATA_LOC_IN_PROJECT)
+
+
+def get_path_in_project(filename):
+    """Get the realpath to a file contained within the project, given its project-relative path"""
+
+    old_cwd = os.getcwd()
+
+    try:
+        os.chdir(os.path.join(psdi_data_conversion.__path__[0], ".."))
+        realpath = os.path.realpath(filename)
+
+    finally:
+        # Change back to the previous directory
+        os.chdir(old_cwd)
+
+    return realpath
+
+
+def get_test_data_loc():
+    """Get the realpath of the base directory containing all data for tests"""
+    return get_path_in_project(TEST_DATA_LOC_IN_PROJECT)
+
+
+def get_input_test_data_loc():
+    """Get the realpath of the base directory containing input data for tests"""
+    return get_path_in_project(INPUT_TEST_DATA_LOC_IN_PROJECT)
+
+
+def get_output_test_data_loc():
+    """Get the realpath of the base directory containing expected output data for tests"""
+    return get_path_in_project(OUTPUT_TEST_DATA_LOC_IN_PROJECT)
 
 
 @dataclass
 class ConversionTestInfo:
     """Information about a tested conversion."""
 
+    run_type: str
+    """One of "library", "cla", or "gui", describing which type of test run was performed"""
+
     test_spec: SingleConversionTestSpec
     """The specification of the test conversion which was run to produce this"""
 
@@ -50,20 +86,23 @@ class ConversionTestInfo:
     captured_stderr: str | None = None
     """Any output to stderr while the test was run"""
 
+    exc_info: pytest.ExceptionInfo | None = None
+    """If the test conversion raised an exception, that exception's info, otherwise None"""
+
     @property
     def qualified_in_filename(self):
         """Get the fully-qualified name of the input file"""
-        return os.path.join(self.input_dir, self.test_spec.filename)
+        return os.path.realpath(os.path.join(self.input_dir, self.test_spec.filename))
 
     @property
     def qualified_out_filename(self):
         """Get the fully-qualified name of the output file"""
-        return os.path.join(self.output_dir, self.test_spec.out_filename)
+        return os.path.realpath(os.path.join(self.output_dir, self.test_spec.out_filename))
 
     @property
     def qualified_log_filename(self):
         """Get the fully-qualified name of the log file"""
-        return os.path.join(self.output_dir, self.test_spec.log_filename)
+        return os.path.realpath(os.path.join(self.output_dir, self.test_spec.log_filename))
 
     @property
     def qualified_global_log_filename(self):
@@ -71,28 +110,6 @@ class ConversionTestInfo:
         return self.test_spec.global_log_filename
 
 
-@dataclass
-class LibraryConversionTestInfo(ConversionTestInfo):
-    """Information about a tested conversion, specifically for when it was tested through a call to the library"""
-
-    exc_info: pytest.ExceptionInfo | None = None
-    """If the test conversion raised an exception, that exception's info, otherwise None"""
-
-
-@dataclass
-class CLAConversionTestInfo(ConversionTestInfo):
-    """Information about a tested conversion, specifically for when it was tested through a the command-line
-    application (CLA)
-    """
-
-
-@dataclass
-class GUIConversionTestInfo(ConversionTestInfo):
-    """Information about a tested conversion, specifically for when it was tested through the GUI (the local version of
-    the web app)
-    """
-
-
 @dataclass
 class ConversionTestSpec:
     """Class providing a specification for a test file conversion.
@@ -102,13 +119,16 @@ class ConversionTestSpec:
     (as if using zip on the multiple lists) to test each element in turn.
     """
 
+    name: str
+    """The name of this test specification"""
+
     filename: str | Iterable[str] = "nacl.cif"
     """The name of the input file, relative to the input test data location, or a list thereof"""
 
     to_format: str | Iterable[str] = "pdb"
     """The format to test converting the input file to, or a list thereof"""
 
-    name: str | Iterable[str] = CONVERTER_DEFAULT
+    converter_name: str | Iterable[str] = CONVERTER_DEFAULT
     """The name of the converter to be used for the test, or a list thereof"""
 
     conversion_kwargs: dict[str, Any] | Iterable[dict[str, Any]] = field(default_factory=dict)
@@ -118,12 +138,26 @@ class ConversionTestSpec:
     expect_success: bool | Iterable[bool] = True
     """Whether or not to expect the test to succeed"""
 
+    skip: bool | Iterable[bool] = False
+    """If set to true, this test will be skipped and not run. Can also be set individually for certain tests within an
+    array. This should typically only be used when debugging to skip working tests to more easily focus on non-working
+    tests"""
+
     callback: (Callable[[ConversionTestInfo], str] |
                Iterable[Callable[[ConversionTestInfo], str]] | None) = None
     """Function to be called after the conversion is performed to check in detail whether results are as expected. It
     should take as its only argument a `ConversionTestInfo` and return a string. The string should be empty if the check
     is passed and should explain the failure otherwise."""
 
+    compatible_with_library: bool = True
+    """Whether or not this test spec is compatible with being run through the Python library, default True"""
+
+    compatible_with_cla: bool = True
+    """Whether or not this test spec is compatible with being run through the command-line application, default True"""
+
+    compatible_with_gui: bool = True
+    """Whether or not this test spec is compatible with being run through the GUI, default True"""
+
     def __post_init__(self):
         """Regularize the lengths of all attribute lists, in case some were provided as single values and others as
         lists, and set up initial values
@@ -131,7 +165,10 @@ class ConversionTestSpec:
 
         # To ease maintainability, we get the list of this class's attributes automatically from its __dict__, excluding
         # any which start with an underscore
-        self._l_attr_names: list[str] = [attr_name for attr_name in self.__dict__ if not attr_name.startswith("_")]
+        self._l_attr_names: list[str] = [attr_name for attr_name in self.__dict__ if
+                                         not (attr_name.startswith("_") or
+                                              attr_name == "name" or
+                                              attr_name.startswith("compatible"))]
 
         l_single_val_attrs = []
         self._len: int = 1
@@ -172,6 +209,9 @@ class ConversionTestSpec:
             if attr_name in l_single_val_attrs:
                 setattr(self, attr_name, [getattr(self, attr_name)]*self._len)
 
+        # Check if all tests should be skipped
+        self.skip_all = all(self.skip)
+
     def __len__(self):
         """Get the length from the member - valid only after `__post_init__` has been called"""
         return self._len
@@ -196,7 +236,7 @@ class SingleConversionTestSpec:
     to_format: str
     """The format to test converting the input file to"""
 
-    name: str | Iterable[str] = CONVERTER_DEFAULT
+    converter_name: str | Iterable[str] = CONVERTER_DEFAULT
     """The name of the converter to be used for the test"""
 
     conversion_kwargs: dict[str, Any] = field(default_factory=dict)
@@ -206,6 +246,9 @@ class SingleConversionTestSpec:
     expect_success: bool = True
     """Whether or not to expect the test to succeed"""
 
+    skip: bool = False
+    """If set to True, this test will be skipped, always returning success"""
+
     callback: (Callable[[ConversionTestInfo], str] | None) = None
     """Function to be called after the conversion is performed to check in detail whether results are as expected. It
     should take as its only argument a `ConversionTestInfo` and return a string. The string should be empty if the check
@@ -243,9 +286,14 @@ def run_test_conversion_with_library(test_spec: ConversionTestSpec):
     with TemporaryDirectory("_input") as input_dir, TemporaryDirectory("_output") as output_dir:
         # Iterate over the test spec to run each individual test it defines
         for single_test_spec in test_spec:
+            if single_test_spec.skip:
+                print(f"Skipping single test spec {single_test_spec}")
+                continue
+            print(f"Running single test spec: {single_test_spec}")
             _run_single_test_conversion_with_library(test_spec=single_test_spec,
                                                      input_dir=input_dir,
                                                      output_dir=output_dir)
+            print(f"Success for test spec: {single_test_spec}")
 
 
 def _run_single_test_conversion_with_library(test_spec: SingleConversionTestSpec,
@@ -264,9 +312,9 @@ def _run_single_test_conversion_with_library(test_spec: SingleConversionTestSpec
     """
 
     # Symlink the input file to the input directory
-    qualified_in_filename = os.path.join(input_dir, test_spec.filename)
+    qualified_in_filename = os.path.realpath(os.path.join(input_dir, test_spec.filename))
     try:
-        os.symlink(os.path.join(INPUT_TEST_DATA_LOC, test_spec.filename),
+        os.symlink(os.path.join(get_input_test_data_loc(), test_spec.filename),
                    qualified_in_filename)
     except FileExistsError:
         pass
@@ -279,7 +327,7 @@ def _run_single_test_conversion_with_library(test_spec: SingleConversionTestSpec
         if test_spec.expect_success:
             run_converter(filename=qualified_in_filename,
                           to_format=test_spec.to_format,
-                          name=test_spec.name,
+                          name=test_spec.converter_name,
                           upload_dir=input_dir,
                           download_dir=output_dir,
                           **test_spec.conversion_kwargs)
@@ -288,7 +336,7 @@ def _run_single_test_conversion_with_library(test_spec: SingleConversionTestSpec
             with pytest.raises(Exception) as exc_info:
                 run_converter(filename=qualified_in_filename,
                               to_format=test_spec.to_format,
-                              name=test_spec.name,
+                              name=test_spec.converter_name,
                               upload_dir=input_dir,
                               download_dir=output_dir,
                               **test_spec.conversion_kwargs)
@@ -301,13 +349,14 @@ def _run_single_test_conversion_with_library(test_spec: SingleConversionTestSpec
 
     # Compile output info for the test and call the callback function if one is provided
     if test_spec.callback:
-        test_info = LibraryConversionTestInfo(test_spec=test_spec,
-                                              input_dir=input_dir,
-                                              output_dir=output_dir,
-                                              success=success,
-                                              captured_stdout=stdout,
-                                              captured_stderr=stderr,
-                                              exc_info=exc_info)
+        test_info = ConversionTestInfo(run_type="library",
+                                       test_spec=test_spec,
+                                       input_dir=input_dir,
+                                       output_dir=output_dir,
+                                       success=success,
+                                       captured_stdout=stdout,
+                                       captured_stderr=stderr,
+                                       exc_info=exc_info)
         callback_msg = test_spec.callback(test_info)
         assert not callback_msg, callback_msg
 
@@ -324,9 +373,14 @@ def run_test_conversion_with_cla(test_spec: ConversionTestSpec):
     with TemporaryDirectory("_input") as input_dir, TemporaryDirectory("_output") as output_dir:
         # Iterate over the test spec to run each individual test it defines
         for single_test_spec in test_spec:
+            if single_test_spec.skip:
+                print(f"Skipping single test spec {single_test_spec}")
+                continue
+            print(f"Running single test spec: {single_test_spec}")
             _run_single_test_conversion_with_cla(test_spec=single_test_spec,
                                                  input_dir=input_dir,
                                                  output_dir=output_dir)
+            print(f"Success for test spec: {single_test_spec}")
 
 
 def _run_single_test_conversion_with_cla(test_spec: SingleConversionTestSpec,
@@ -345,9 +399,9 @@ def _run_single_test_conversion_with_cla(test_spec: SingleConversionTestSpec,
     """
 
     # Symlink the input file to the input directory
-    qualified_in_filename = os.path.join(input_dir, test_spec.filename)
+    qualified_in_filename = os.path.realpath(os.path.join(input_dir, test_spec.filename))
     try:
-        os.symlink(os.path.join(INPUT_TEST_DATA_LOC, test_spec.filename),
+        os.symlink(os.path.join(get_input_test_data_loc(), test_spec.filename),
                    qualified_in_filename)
     except FileExistsError:
         pass
@@ -359,7 +413,7 @@ def _run_single_test_conversion_with_cla(test_spec: SingleConversionTestSpec,
         if test_spec.expect_success:
             run_converter_through_cla(filename=qualified_in_filename,
                                       to_format=test_spec.to_format,
-                                      name=test_spec.name,
+                                      name=test_spec.converter_name,
                                       input_dir=input_dir,
                                       output_dir=output_dir,
                                       log_file=os.path.join(output_dir, test_spec.log_filename),
@@ -369,7 +423,7 @@ def _run_single_test_conversion_with_cla(test_spec: SingleConversionTestSpec,
             with pytest.raises(SystemExit) as exc_info:
                 run_converter_through_cla(filename=qualified_in_filename,
                                           to_format=test_spec.to_format,
-                                          name=test_spec.name,
+                                          name=test_spec.converter_name,
                                           input_dir=input_dir,
                                           output_dir=output_dir,
                                           log_file=os.path.join(output_dir, test_spec.log_filename),
@@ -377,7 +431,7 @@ def _run_single_test_conversion_with_cla(test_spec: SingleConversionTestSpec,
             # Get the success from whether or not the exit code is 0
             success = not exc_info.value.code
 
-        qualified_out_filename = os.path.join(output_dir, test_spec.out_filename)
+        qualified_out_filename = os.path.realpath(os.path.join(output_dir, test_spec.out_filename))
 
         # Determine success based on whether or not the output file exists with non-zero size
         if not os.path.isfile(qualified_out_filename) or os.path.getsize(qualified_out_filename) == 0:
@@ -390,12 +444,13 @@ def _run_single_test_conversion_with_cla(test_spec: SingleConversionTestSpec,
 
     # Compile output info for the test and call the callback function if one is provided
     if test_spec.callback:
-        test_info = CLAConversionTestInfo(test_spec=test_spec,
-                                          input_dir=input_dir,
-                                          output_dir=output_dir,
-                                          success=success,
-                                          captured_stdout=stdout,
-                                          captured_stderr=stderr)
+        test_info = ConversionTestInfo(run_type="cla",
+                                       test_spec=test_spec,
+                                       input_dir=input_dir,
+                                       output_dir=output_dir,
+                                       success=success,
+                                       captured_stdout=stdout,
+                                       captured_stderr=stderr)
         callback_msg = test_spec.callback(test_info)
         assert not callback_msg, callback_msg
 
@@ -426,6 +481,8 @@ def run_converter_through_cla(filename: str,
         The directory which contains the output file
     log_file : str
         The desired name of the log file
+    conversion_kwargs : Any
+        Additional arguments describing the conversion
     """
 
     # Start the argument string with the arguments we will always include

{psdi_data_conversion-0.0.35.dist-info → psdi_data_conversion-0.0.37.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: psdi_data_conversion
-Version: 0.0.35
+Version: 0.0.37
 Summary: Chemistry file format conversion service, provided by PSDI
 Project-URL: Homepage, https://data-conversion.psdi.ac.uk/
 Project-URL: Documentation, https://psdi-uk.github.io/psdi-data-conversion/
@@ -278,7 +278,10 @@ This is the repository for the PSDI PF2 Chemistry File Format Conversion project
   - [Installation and Setup](#installation-and-setup)
   - [Running the App](#running-the-app)
 - [Testing](#testing)
-- [Licencing](#licencing)
+- [Troubleshooting](#troubleshooting)
+  - [OSError: [Errno 24] Too many open files](#oserror-errno-24-too-many-open-files)
+  - [Errors running c2x or Atomsk converters](#errors-running-c2x-or-atomsk-converters)
+- [Licensing](#licensing)
 - [Contributors](#contributors)
 - [Funding](#funding)
 
@@ -312,15 +315,17 @@ This is the repository for the PSDI PF2 Chemistry File Format Conversion project
 - `test_data`
   - (Files used for testing the project)
 - `tests`
-  - (Unit tests for the project)
+  - `gui`
+    - (Unit tests for the GUI, aka the local version of the web app)
+  - `python`
+    - (Unit tests for the Python library and command-line application)
 - `CHANGELOG.md` (Updates since initial public release)
 - `CONTRIBUTING.md` (Guidelines and information for contributors to the project)
 - `DOCKERFILE` (Dockerfile for image containerising PSDI's data conversion service)
-- `LICENSE` (Apache Licence version 2.0)
+- `LICENSE` (Apache License version 2.0)
 - `pyproject.toml` (Python project metadata and settings)
 - `README.md` (This file)
 - `requirements.txt` (Requirements for the web app deployment of this project)
-- `run_local.sh` (Helper script to run the web app locally)
 
 ## Requirements
 
@@ -403,13 +408,21 @@ In addition to the dependencies listed above, this project uses the assets made
 
 ### Installation
 
-The CLA and Python library are installed together. This package is not yet available on PyPI, and so must be installed locally. This can be done most easily with:
+The CLA and Python library are installed together. This project is available on PyPI, and so can be installed via pip with:
+
+```bash
+pip install psdi-data-conversion
+```
+
+If you wish to install from source, this can be done most easily by cloning the project and then executing:
 
 ```bash
 pip install .
 ```
 
-executed from this project's directory. You can also replace the '.' in this command with the path to this project's directory to install it from elsewhere.
+from this project's directory. You can also replace the '.' in this command with the path to this project's directory to install it from elsewhere.
+
+**Note:** This project uses git to determine the version number. If you clone the repository, you won't have to do anything special here, but if you get the source e.g. by extracting a release archive, you'll have to do one additional step before running the command above. If you have git installed, simply run `git init` in the project directory and it will be able to install. Otherwise, edit the project's `pyproject.toml` file to uncomment the line that sets a fixed version, and comment out the lines that set it up to determine the version from git - these are pointed out in the comments there.
 
 Depending on your system, it may not be possible to install packages in this manner without creating a virtual environment to do so in. You can do this by first installing the `venv` module for Python3 with e.g.:
 
@@ -572,51 +585,25 @@ Enter https://data-conversion.psdi.ac.uk/ in a browser. Guidance on usage is giv
 
 ### Installation and Setup
 
-Install the package and its requirements, including the optional requirements used to run the GUI locally, by executing the following command from this project's directory:
+This project is available on PyPI, and so can be installed via pip, including the necessary dependencies for the GUI, with:
 
 ```bash
-pip install .'[gui]'
+pip install psdi-data-conversion'[gui]'
 ```
 
-If your system does not allow installs in this manner, it may be necessary to set up a virtual environment. See the instructions in the [command-line application installation](#installation) section above for how to do that, and then try to install again once you've set one up and activated it.
-
-If you've cloned this repository, you can use the `run_local.sh` bash script to run the application. Otherwise (e.g. if you've installed from a wheel or PyPI), copy and paste the following into a script:
+If you wish to install the project locally from source, this can be done most easily by cloning the project and then executing:
 
 ```bash
-#!/bin/bash
-
-# The envvar MAX_FILESIZE can be used to set the maximum allowed filesize in MB - 0 indicates no maximum
-if [ -z $MAX_FILESIZE ]; then
-  export MAX_FILESIZE=0
-fi
-
-# Logging control - "full" sets server-style logging, which is necessary to produce the output logs with the expected
-# names. This should not be changed, or else errors will occur
-export LOG_MODE=full
-
-# The level to log at. Leave blank for defaults, which logs at INFO level for user output and ERROR level for the server
-# log and stdout. If set to a different value here (e.g. DEBUG), all these channels will be set to that level
-export LOG_LEVEL=
-
-# The envvar SERVICE_MODE can be set to "true" to make this behave as if it's running as the public web service -
-# uncomment the following line to enable that
-# export SERVICE_MODE=true
-
-# Uncomment the following line to enable debug mode
-# export FLASK_ENV=development
-
-# Execute a local run of the application from the proper path
-
-PACKAGE_PATH=`python -c "import psdi_data_conversion; print(psdi_data_conversion.__path__[0])"`
-cd $PACKAGE_PATH/..
-python -m flask --app psdi_data_conversion/app.py run
+pip install .'[gui]'
 ```
 
-If desired, you can modify the environmental variables set in this script to modify the operation - see the comments on each for details.
+**Note:** This project uses git to determine the version number. If you clone the repository, you won't have to do anything special here, but if you get the source e.g. by extracting a release archive, you'll have to do one additional step before running the command above. If you have git installed, simply run `git init` in the project directory and it will be able to install. Otherwise, edit the project's `pyproject.toml` file to uncomment the line that sets a fixed version, and comment out the lines that set it up to determine the version from git - these are pointed out in the comments there.
+
+If your system does not allow installation in this manner, it may be necessary to set up a virtual environment. See the instructions in the [command-line application installation](#installation) section above for how to do that, and then try to install again once you've set one up and activated it.
 
 ### Running the App
 
-Run the `run_local.sh` script to start the server. You can then access the website by going to <http://127.0.0.1:5000> in a browser (this will also be printed in the terminal, and you can CTRL+click it there to open it in your default browser). Guidance for using the app is given on each page of it.
+Once installed, the command-line script `psdi-data-convert-gui` will be made available, which can be called to start the server. You can then access the website by going to <http://127.0.0.1:5000> in a browser (this will also be printed in the terminal, and you can CTRL+click it there to open it in your default browser). Guidance for using the app is given on each page of it. When you're finished with the app, key CTRL+C in the terminal where you called the script to shut down the server, or, if the process was backgrounded, kill the appropriate process.
 
 In case of problems when using Chrome, try opening Chrome from the command line:
 open -a "Google Chrome.app" --args --allow-file-access-from-files
@@ -639,28 +626,80 @@ To test the CLA and Python library, install the optional testing requirements lo
 
 ```bash
 pip install .'[test]'
-pytest
+pytest tests/python
 ```
 
 To test the local version of the web app, install the GUI testing requirements locally (which also include the standard GUI requirements and standard testing requirements), start the server, and test by executing the GUI test script:
 
 ```bash
 pip install .'[gui-test]'
-./run_local.sh & # Start the server for the web app in the background
-cd tests/selenium
-./run.sh
-kill %1 # Stop the web server - it may have a different job ID. If you don't know the job ID, you can alternatively call "fg" to bring the job to the foreground, then type CTRL+c to stop it
+pytest tests/gui
+```
+
+Both of these sets of tests can also be run together if desired through:
+
+```bash
+pip install .'[gui-test]'
+pytest
+```
+
+## Troubleshooting
+
+This section presents solutions for commonly-encountered issues.
+
+### OSError: [Errno 24] Too many open files
+
+You may see the error:
+
+```
+OSError: [Errno 24] Too many open files
+```
+
+while running the command-line application, using the Python library, or running tests This error is caused by a program hitting the limit of the number of open filehandles allowed by the OS. This limit is typically set to 1024 on Linux systems and 256 on MacOS systems, and thus this issue occurs much more often on the latter. You can see what your current limit is by running the command:
+
+```bash
+ulimit -a | grep "open files"
+```
+
+This limit can be temporarily increased for the current terminal session by running the command:
+
+```bash
+ulimit -n 1024 # Or another, higher number
+```
+
+First, try increasing the limit and then redo the operation which caused this error to see if this resolves it. If this does, you can make this change permanent in a few ways, the easiest of which is to add this command to your `.bashrc` file so it will be set for every new terminal session.
+
+If you see this error when the filehandle limit is already set to a high value such as 1024, this may indicate the presence of a bug in the project which causes a leaking of filehandles, so please open an issue about it, pasting the error you get and the details of your system, particularly including your current filehandle limit.
+
+### Errors running c2x or Atomsk converters
+
+We provide support for the c2x and Atomsk converters by packing binaries which support common Linux and MacOS platforms with this project, but we cannot guarantee universal support for these binaries. In particular, they may rely on dynamically-linked libraries which aren't installed on your system.
+
+Look through the error message you received for messages such as "Library not loaded" or "no such file", and see if they point to the name of a library which you can try installing. For instance, if you see that it's searching for `libquadmath.0.dylib` but not finding it, you can try installing this library. In this case, this library can be installed through apt with:
+
+```bash
+sudo apt install libquadmath0
 ```
 
-## Licencing
+or through brew via:
+
+```bash
+brew install gcc
+```
+
+Alternatively, you can run your own versions of the `c2x` and `atomsk` binaries with this project. Compile them yourself however you wish - see the projects at https://github.com/codenrx/c2x and https://github.com/pierrehirel/atomsk and follow their instructions to build a binary on your system. Once you've done so, add the binary to your `$PATH`, and this project will pick that up and use it in preference to the prepackaged binary.
+
+On the other hand, it's possible that an error of this sort will occur if you have a non-working binary of one of these converters in your `$PATH`. If this might be the case, you can try removing it and see if the prepackaged binary works for you, or else recompile it to try to fix errors.
+
+## Licensing
 
 This project is provided under the Apache License version 2.0, the terms of which can be found in the file `LICENSE`.
 
-This project redistributes compiled binaries for the Atomsk and c2x converters. These are both licenced under the
+This project redistributes compiled binaries for the Atomsk and c2x converters. These are both licensed under the
 GNU General Public License version 3 and are redistributed per its terms. Any further redistribution of these binaries,
-including redistribution of this project as a whole, including them, must also follow the terms of this licence.
+including redistribution of this project as a whole, including them, must also follow the terms of this license.
 
-This requires conspicuously displaying notice of this licence, providing the text of of the licence (provided here in
+This requires conspicuously displaying notice of this license, providing the text of of the license (provided here in
 the files `psdi_data_conversion/bin/LICENSE_C2X` and `psdi_data_conversion/bin/LICENSE_ATOMSK`), and appropriately
 conveying the source code for each of these. Their respective source code may be found at: