psdi-data-conversion 0.0.35__tar.gz → 0.0.37__tar.gz

{psdi_data_conversion-0.0.35 → psdi_data_conversion-0.0.37}/CONTRIBUTING.md

@@ -297,6 +297,22 @@ For debugging python issues, it's recommended to install the package in editable
 pip install --editable .'[gui-test]'
 ```
 
+### Running Unit Tests
+
+The GUI unit tests require a web driver to be installed, and will install one if one isn't. To avoid repeated unnecessary API calls for the installation, you can set the environmental variable `DRIVER` when running tests to the location of your driver. This can be set to be automatically picked up by many IDEs by setting this in a `.env` file in the root of your project, e.g.:
+
+```
+DRIVER=~/.wdm/drivers/geckodriver/linux64/v0.36.0/geckodriver
+```
+
+To get the address of your driver, you can run the following in a Python terminal from within this projects virtual environment (after installing the `[gui-test]` optional dependencies):
+
+```python
+from webdriver_manager.firefox import GeckoDriverManager
+driver_path = GeckoDriverManager().install()
+print(f"Gecko driver installed to: {driver_path}")
+```
+
 ## Continuous Integration
 
 This project uses various GitHub workflows to perform Continuous Integration tasks. These can be found in the `.github/workflows` folder. The files which start with "ci-" are the directly-triggered workflows, and the files which start with "job-" are reusable workflows called by the former. These workflows handle the following tasks:
@@ -310,7 +326,7 @@ See the commons within the files for further details.
 
 ## Publishing
 
-The Python library, CLA, and local GUI are (planned to be) published as a Python package via PyPI. This section describes how the package is set up and how it's published.
+The Python library, CLA, and local GUI are published as a Python package via PyPI. This section describes how the package is set up and how it's published.
 
 ### Package Setup
 
@@ -318,11 +334,11 @@ The package's setup is defined in the `pyproject.toml` file. This defines the pr
 
 The package uses [Hatch](https://hatch.pypa.io/latest/) for its build backend, as it is simpler to configure than the classic [Setuptools](https://setuptools.pypa.io/en/latest/userguide/) and provides some useful extensibility.
 
-The version of the package is set to be determined from the version control system, meaning on the release branch, the version will always match the latest tag.
+The version of the package is set to be determined from the version control system, meaning on the release branch, the version will always match the latest tag. This alleviates us of having to manually maintain the version for the package to keep it correct, but does result in some quirks. It's a bit fussier to set up (though that's done now), and it makes the user take an extra step if they want to install from source but haven't cloned the repository - this is noted in the installation instructions in the README.
 
 ### Initial Publication
 
-This section details the plan for the initial publication of this package - after this is complete, this section will be left in for reference in case of future need.
+This section details the proceduce for the initial publication of this package - now that this is complete, this section is left in for reference in case of future need.
 
 First, it's necessary to install a couple required packages in order to build a Python package: `build` to build it and `twine` to upload it. These can be installed with pip via:
 
@@ -350,6 +366,14 @@ To upload, follow [this tutorial](https://packaging.python.org/en/latest/tutoria
 
 The `ci-release.yml` workflow is planned to publish any new releases to PyPI after the initial publication. This can be set up by uncommenting the relevant lines in this file, possibly updating the `job-publish-pypi.yml` to enable this (testing will be necessary), and setting up Trusted Publishing for the project on PyPI (see [guide](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-pypi))
 
+### Project Management
+
+This project is published on PyPI at https://pypi.org/project/psdi-data-conversion/ and on TestPyPI at https://test.pypi.org/project/psdi-data-conversion/. Maintainers can manage the project through the "Manage" link on that page or from their own projects page.
+
+The most important setting to be aware of here is Publishing -> Trusted Publisher Management. This is the system used to allow automatic publishing of releases from GitHub. It's set up so that the current project, organisation, environment, and workflow for publishing are approved. If any of these change, this will need to be updated by adding a new trusted publisher with the new settings (on both PyPI and TestPyPI) and removing the old one.
+
+The management page can also be used to add or remove collaborators through the Collaborators tab. Generally the project on these sites doesn't require much maintenance, but at least a few active collaborators should be on it at all times to avoid getting locked out if someone is suddenly unavailable.
+
 ## Deployment
 
 Deployment is handled by the `job-deploy-k8s.yml` reusable workflow, which is triggered from `ci-main.yml` to deploy to dev on each push to `main` and `ci-release.yml` to deploy to staging on each push to `release`. When a push to production is desired, it must be triggered manually by calling the `ci-deploy-production.yml` workflow on the `release` branch (it's set up to fail if run on any other branch).

{psdi_data_conversion-0.0.35 → psdi_data_conversion-0.0.37}/PKG-INFO

@@ -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:
 

{psdi_data_conversion-0.0.35 → psdi_data_conversion-0.0.37}/README.md

@@ -33,7 +33,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)
 
@@ -67,15 +70,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
 
@@ -158,13 +163,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.:
 
@@ -327,51 +340,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
@@ -394,28 +381,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: