diff --git a/.conda/bin/build b/.conda/bin/build new file mode 100755 index 000000000..2714131a2 --- /dev/null +++ b/.conda/bin/build @@ -0,0 +1,15 @@ +#!/usr/bin/env bash + +DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" + +export BRAINIAK_HOME=$DIR/../../ + +# See run-tests.sh +export MKL_THREADING_LAYER=GNU + +if [ -z ${CONDA_HOME+dummy} ] +then + CONDA_HOME="$HOME"/miniconda3 +fi + +"$CONDA_HOME"/bin/conda build "$DIR"/.. diff --git a/.conda/bin/docker b/.conda/bin/docker new file mode 100755 index 000000000..01d9c0e69 --- /dev/null +++ b/.conda/bin/docker @@ -0,0 +1,6 @@ +#!/usr/bin/env bash + +DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" + +# Need to run apt update && apt install -y build-essential curl git +docker run --rm -w /src -v $DIR/../..:/src -ti ubuntu:trusty /bin/bash diff --git a/.conda/bin/install-miniconda b/.conda/bin/install-miniconda new file mode 100755 index 000000000..8817d81da --- /dev/null +++ b/.conda/bin/install-miniconda @@ -0,0 +1,28 @@ +#!/usr/bin/env bash + +# Install Miniconda. +echo "" +echo "Installing a fresh version of Miniconda." +MINICONDA_URL="https://repo.continuum.io/miniconda" + +MINICONDA_FILE="Miniconda3-latest-Linux-x86_64.sh" +if [[ "$OSTYPE" == "darwin"* ]]; then + MINICONDA_FILE="Miniconda3-latest-MacOSX-x86_64.sh" +fi + +curl -L "${MINICONDA_URL}/${MINICONDA_FILE}" -o ~/${MINICONDA_FILE} + +# Update an existing miniconda installation, if it exists +bash ~/$MINICONDA_FILE -b -u + +# Clean up +rm -f ~/${MINICONDA_FILE} + +# Configure conda. +echo "" +echo "Configuring conda." +source ~/miniconda3/bin/activate root +conda config --add channels conda-forge --add channels defaults +conda config --set show_channel_urls true +conda install --yes --quiet conda-build +source deactivate diff --git a/.conda/build.sh b/.conda/build.sh new file mode 100755 index 000000000..63535aa96 --- /dev/null +++ b/.conda/build.sh @@ -0,0 +1,15 @@ +#!/bin/bash + +if [[ "$OSTYPE" == "darwin"* ]]; then + export MACOSX_DEPLOYMENT_TARGET=10.9 + export CC=$(which clang) + export CXX=$(which clang++) +fi + +echo $PREFIX + +# Install pymanopt via pip because there isn't a conda package +$PYTHON -m pip install pymanopt + +# NOTE: This is the recommended way to install packages +$PYTHON setup.py install --single-version-externally-managed --record=record.txt diff --git a/.conda/meta.yaml b/.conda/meta.yaml new file mode 100644 index 000000000..67268c18e --- /dev/null +++ b/.conda/meta.yaml @@ -0,0 +1,67 @@ +{% set conda_package_nonexistent = ( + "pymanopt", +) %} +{% set data = load_setup_py_data() %} + +package: + # Repeating name because of the following issue: + # https://github.com/conda/conda-build/issues/2475 + name: brainiak + version: {{ GIT_DESCRIBE_TAG[1:] }} + +about: + home: {{ data.get('url') }} + license: {{ data.get('license') }} + summary: {{ data.get('description') }} + +source: + path: ../ + +build: + number: {{ GIT_DESCRIBE_NUMBER }} + script_env: + + # We need the source directory because conda removes source / working + # directories by the time we reach the test phase. We can optionally pass in + # the --keep-old-work flag later on to use the $PREFIX/work directory + - BRAINIAK_HOME + - MKL_THREADING_LAYER + +requirements: + build: + - {{ compiler('cxx') }} + + host: + - python + - setuptools + - pip + - openmp + {% for req in data.get('setup_requires', []) + if req not in conda_package_nonexistent -%} + - {{req}} + {% endfor %} + {% for req in data.get('install_requires', []) + if req not in conda_package_nonexistent -%} + - {{req}} + {% endfor %} + + run: + - python + - openmp + {% for req in data.get('install_requires', []) + if req not in conda_package_nonexistent -%} + - {{req}} + {% endfor %} + +test: + commands: + - find $BRAINIAK_HOME/tests | grep pycache | xargs rm -rf + - mpiexec -n 2 pytest $BRAINIAK_HOME + + # Known issue: https://github.com/travis-ci/travis-ci/issues/4704#issuecomment-348435959 + - python -c 'import os,sys,fcntl; flags = fcntl.fcntl(sys.stdout, fcntl.F_GETFL); fcntl.fcntl(sys.stdout, fcntl.F_SETFL, flags&~os.O_NONBLOCK);' + - conda inspect linkages -p $PREFIX brainiak # [not win] + - conda inspect objects -p $PREFIX brainiak # [osx] + requires: + - pytest + - numdifftools diff --git a/.travis.yml b/.travis.yml index af49ccd52..21bab5f5a 100644 --- a/.travis.yml +++ b/.travis.yml @@ -40,6 +40,17 @@ matrix: env: *macos_env before_install: *macos_before_install + # Build and test conda packages + - os: linux + dist: trusty + install: ./.conda/bin/install-miniconda + script: ./.conda/bin/build + + - os: osx + osx_image: xcode8 + install: ./.conda/bin/install-miniconda + script: ./.conda/bin/build + install: - python3 -m pip install -U pip codecov diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 71c35b6cb..c39a58952 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -281,6 +281,22 @@ Making a release This information is only of interest to the core contributors who have the right to make releases. +Before making a release, ensure that: + +1. The following environment variables are set:: + + export $CONDA_HOME=/path/to/miniconda3 + +2. The following Conda channels are enabled:: + + conda config --add channels conda-forge --add channels defaults + +3. The following Conda packages are installed:: + + conda install conda-build anaconda-client + +To make a release: + 1. Choose a release number, ``v``. We follow `Semantic Versioning `_, although we omit the patch number when it is 0. @@ -300,7 +316,7 @@ right to make releases. git tag v -4. Create and test the distribution package:: +4. Create and test the source distribution package:: python3 setup.py sdist tar -xf dist/brainiak-.tar.gz @@ -313,3 +329,15 @@ right to make releases. git tag --push twine upload dist/brainiak-.tar.gz + + +7. Create and test Conda packages (repeat command for all OSes and Python + versions); requires the ``conda-build`` Conda package:: + + .conda/bin/build + +8. Upload the built Conda package (repeat command for all OSes and Python + versions); requires the ``anaconda-client`` Conda package:: + + anaconda upload -u brainiak \ + $CONDA_HOME/conda-bld//brainiak--.tar.bz2 diff --git a/README.rst b/README.rst index 3c4f33b1b..0046e5fc4 100644 --- a/README.rst +++ b/README.rst @@ -23,93 +23,19 @@ To reduce verbosity, we may refer to the Brain Imaging Analysis Kit using the package name), we use ``brainiak``. -Requirements -============ - -We support Linux and MacOS with Python version 3.4 or higher. Most of the -dependencies will be installed automatically. However, a few need to be -installed manually. - - -Linux ------ - -Install the following packages (Ubuntu 16.04 is used in these instructions):: - - apt install build-essential libgomp1 libmpich-dev mpich python3-dev \ - python3-pip python3-venv - -Install updated version of the following Python packages:: - - python3 -m pip install --user -U pip - -Note the ``--user`` flag, which instructs Pip to not overwrite system -files. You must add ``$HOME/.local/bin`` to your ``$PATH`` to be able to run -the updated Pip, e.g., by adding the following line to ``$HOME/.profile`` -and launching a new login shell (e.g., logout or execute ``bash -l``):: - - PATH="$HOME/.local/bin:$PATH" - - -MacOS ------ - -Install the Xcode Command Line Tools:: - - xcode-select --install - -Install ``brew`` from https://brew.sh. If you already have ``brew``, examine -the output of the following command to make sure it is working:: - - brew doctor - -Then install the following:: - - brew install llvm cmake mpich python3 - -Note that if your MacOS does not have ``gcc`` (a prerequisite of ``mpich``), -it will take a long time (perhaps over an hour) to install ``gcc`` from source for you. - -You must instruct programs to use this ``clang`` version at ``/usr/local/opt/llvm/bin``. -One way to do this, which -works for most programs, is setting the ``CC`` environment variable. You can -add the following lines to ``$HOME/.profile`` (or ``$HOME/.bash_profile``, if -you have one). For them to take effect, you must logout or launch a new login -shell, e.g., ``bash -l``:: - - export CC=/usr/local/opt/llvm/bin/clang - export CXX=/usr/local/opt/llvm/bin/clang++ - -In addition, you also need to specify the directories that the newly installed `clang` -will seek for compiling and linking:: - - export LDFLAGS="-L/usr/local/opt/llvm/lib "\ - "-Wl,-rpath,/usr/local/opt/llvm/lib $LDFLAGS" - export CPPFLAGS="-I/usr/local/opt/llvm/include $CPPFLAGS" - -Install updated versions of the following Python packages:: - - python3 -m pip install -U pip - - -Installing and upgrading -======================== +Quickstart +========== -The Brain Imaging Analysis Kit is available on PyPI. You can install it (or -upgrade to the latest version) using the following command:: +If you have `Conda `_:: - python3 -m pip install -U brainiak + conda install -c brainiak -c defaults -c conda-forge brainiak -Note that you may see a ``Failed building wheel for brainiak`` message (`issue -#61`_). Installation will proceed despite this failure. You can safely ignore it -as long as you see ``Successfully installed`` at the end. +Otherwise, or if you want to compile from source, install the requirements (see +`docs/installation`) and then install from PyPI:: -.. _issue #61: - https://github.com/brainiak/brainiak/issues/61 + python3 -m pip install brainiak -Until we reach version 1.0, we will only support the latest released version. -Therefore, if you have a problem with an older version, please upgrade to the -latest version before creating an issue on GitHub. +Note that we do not support Windows. Docker @@ -179,4 +105,4 @@ http://brainiak.org." Additionally, if you use `RRIDs `_ to identify resources, please mention BrainIAK as "Brain Imaging Analysis Kit, RRID:SCR_014824". Finally, please cite the publications referenced in the documentation of the BrainIAK modules you -use, e.g., `SRM `_. +use, e.g., `SRM `_. diff --git a/docs/index.rst b/docs/index.rst index 2713a0d73..a41ef972e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,6 +10,7 @@ Table of contents .. toctree:: + installation release_notes api contributing diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 000000000..45f312951 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,107 @@ +============ +Installation +============ + +Conda ++++++ + +Make sure you have the ``conda-forge`` channel active, because some of our +dependencies are not available in the default channels. + +Use our ``brainiak`` channel to install:: + + conda install -c brainiak brainiak + +Note that `~brainiak.funcalign.sssrm.SSSRM` currently uses Theano, which +requires the Xcode Command Line Tools on `MacOS`_. + +Source +++++++ + +Requirements +============ + +We support Linux and MacOS with Python version 3.4 or higher. Most of the +dependencies will be installed automatically. However, a few need to be +installed manually. + + +Linux +----- + +Install the following packages (Ubuntu 16.04 is used in these instructions):: + + apt install build-essential libgomp1 libmpich-dev mpich python3-dev \ + python3-pip python3-venv + +Install updated version of the following Python packages:: + + python3 -m pip install --user -U pip + +Note the ``--user`` flag, which instructs Pip to not overwrite system +files. You must add ``$HOME/.local/bin`` to your ``$PATH`` to be able to run +the updated Pip, e.g., by adding the following line to ``$HOME/.profile`` +and launching a new login shell (e.g., logout or execute ``bash -l``):: + + PATH="$HOME/.local/bin:$PATH" + + +MacOS +----- + +Install the Xcode Command Line Tools:: + + xcode-select --install + +Install ``brew`` from https://brew.sh. If you already have ``brew``, examine +the output of the following command to make sure it is working:: + + brew doctor + +Then install the following:: + + brew install llvm cmake mpich python3 + +Note that if your MacOS does not have ``gcc`` (a prerequisite of ``mpich``), +it will take a long time (perhaps over an hour) to install ``gcc`` from source for you. + +You must instruct programs to use this ``clang`` version at ``/usr/local/opt/llvm/bin``. +One way to do this, which +works for most programs, is setting the ``CC`` environment variable. You can +add the following lines to ``$HOME/.profile`` (or ``$HOME/.bash_profile``, if +you have one). For them to take effect, you must logout or launch a new login +shell, e.g., ``bash -l``:: + + export CC=/usr/local/opt/llvm/bin/clang + export CXX=/usr/local/opt/llvm/bin/clang++ + +In addition, you also need to specify the directories that the newly installed `clang` +will seek for compiling and linking:: + + export LDFLAGS="-L/usr/local/opt/llvm/lib "\ + "-Wl,-rpath,/usr/local/opt/llvm/lib $LDFLAGS" + export CPPFLAGS="-I/usr/local/opt/llvm/include $CPPFLAGS" + +Install updated versions of the following Python packages:: + + python3 -m pip install -U pip + + +Installing and upgrading +======================== + +The Brain Imaging Analysis Kit is available on PyPI. You can install it (or +upgrade to the latest version) using the following command:: + + python3 -m pip install -U brainiak + +Note that you may see a ``Failed building wheel for brainiak`` message (`issue +#61`_). Installation will proceed despite this failure. You can safely ignore it +as long as you see ``Successfully installed`` at the end. + +.. _issue #61: + https://github.com/brainiak/brainiak/issues/61 + +Until we reach version 1.0, we will only support the latest released version. +Therefore, if you have a problem with an older version, please upgrade to the +latest version before creating an issue on GitHub. diff --git a/docs/newsfragments/328.feature b/docs/newsfragments/328.feature new file mode 100644 index 000000000..f8d6d61ca --- /dev/null +++ b/docs/newsfragments/328.feature @@ -0,0 +1 @@ +Added Conda packages. diff --git a/requirements-dev.txt b/requirements-dev.txt index 2a887129e..bf2baa3eb 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -3,10 +3,13 @@ coverage flake8 flake8-print mypy -numdifftools -pytest restructuredtext-lint setuptools_scm sphinx sphinx_rtd_theme towncrier + +# testing +# Also add to .conda/meta.yaml +pytest +numdifftools diff --git a/run-tests.sh b/run-tests.sh index 3271dde2a..00baa0a40 100755 --- a/run-tests.sh +++ b/run-tests.sh @@ -29,6 +29,7 @@ python3 -m pip freeze | grep -qi /brainiak \ } # Define MKL env variable that is required by Theano to run with MKL 2018 +# If removing, also remove from .conda/* export MKL_THREADING_LAYER=GNU mpi_command=mpiexec