conda is an easy to use and maintain software package management system. It provides a simple and painless method for installing OCW and its dependencies across a variety of platforms. |
OCW Installation Instructions
In addition to the standard scientific python packages bundled with most anaconda installations, the following packages will be installed:
Before invoking conda to install the dependencies, it's always a good idea to ensure that your version of conda is up to date. You can do this with:
conda update conda |
Then to install OCW and its dependencies into your conda environment (by default in ~/anaconda or ~/miniconda), you may use:
conda config --add channels conda-forge conda install ocw |
To give yourself some peace of mind that such a simple installation method actually works, it is recommended that you test you installation. The main OCW codebase has some simple examples which may be obtained using:
cd git clone https://github.com/apache/climate.git |
If you do not wish to directly use git, you may download and extract a copy of the code directly from our GitHub page. Once you've obtained the code, head on over to the examples and run one of them.
cd climate/examples python simple_model_to_model_bias.py |
After the evaluation runs you should find a .png file in the examples directory. Congratulations, your install was successful!
Keeping OCW up to date is even more simple than the installation itself. Use:
conda update ocw |
conda update ocw=1.1.0 |
It should be noted that the above instructions will install OCW and its dependencies into your default conda environment. For those users who wish to perform development and testing in a clean and isolated environment, they should instead perform their installations using:
conda create -n ocw ocw |
This will create a new virtual environment named "ocw" with only OCW and its dependencies installed. To activate this environment, use:
source activate ocw |
activate ocw |
To deactivate the environment, use:
source deactivate |
deactivate |
See this page for further documentation on virtual conda environments.
The following section contains some useful information for those in the OCW developer community who are interested in maintaining the conda packages.
It is highly recommended that you read the conda build documentation first. |
We use conda-forge to host the ocw package. To get started, you should fork our feedstock repo. The only file you will need to concern yourself with is recipe/meta.yaml.
There are only a few entries in this file that should be updated. These are as follows:
This should be in the form X.Y.Z which corresponds to the latest release. Note that the ocw source distribution for the given version must first be uploaded to PyPI before making this change, or else conda will fail to build the package. This is main field that you need to change when creating a new release.
Ex:
{% set version = "X.Y.Z" %} |
Where X.Y.Z should be replaced by the version number of the release.
We use sha256 to populate the hash field. This too must be changed with every new release. To do this, you'll need to make sure OpenSSL is installed on your machine:
conda install openssl |
Then to generate the hash string, you may use:
pip download ocw openssl sha256 ocw-X.Y.Z.tar.gz |
Where X.Y.Z should be replaced by the version number of the release. Then you may use the resulting hash string to set the hash in the recipe file. For example:
{% set sha256 = "8f12405ec02ea327b1e0cf65547e409232f67577be6eb348d2ea9011827e2c4a" %} |
A few notes:
skip Should only be set to True for unsupported platforms. This can be achieved using preprocessing selectors. For example, to skip building for Python 3, you would use:
skip: True # [py3k] |
Every listed dependency must be available on some anaconda channel, preferably either the default anaconda channel or the conda-forge channel. If not, consider adding a recipe by submitting a pull request to the conda-forge staged-recipes repo! See the README in the repo for more detailed guidelines. |
This section lists all of the dependencies needed for ocw at build time (not really important since we don't use any extensions) and runtime (much more important). As with the skip field in the build section, certain dependencies can and should be excluded if they are not supported on certain platforms. For example, if a package named "foo" is not compatible with Windows, it may be excluded using:
- foo # [not win] |
This section contains a list of GitHub usernames which have commit rights to the ocw-feedstock repo. If you are a regular contributor to the project and want to help maintain the recipe file, you should add your own GitHub username to this list.