From 28fa427b43c32eba1195c70a99be48f837361db4 Mon Sep 17 00:00:00 2001 From: Daniel Suo Date: Thu, 1 Feb 2018 17:37:03 -0500 Subject: [PATCH 01/13] Add conda packaging --- .conda/bin/install | 30 +++++++++++++++ .conda/bld.bat | 10 +++++ .conda/build.sh | 18 +++++++++ .conda/meta.yaml | 93 ++++++++++++++++++++++++++++++++++++++++++++++ .travis.yml | 11 ++++++ 5 files changed, 162 insertions(+) create mode 100755 .conda/bin/install create mode 100644 .conda/bld.bat create mode 100755 .conda/build.sh create mode 100644 .conda/meta.yaml diff --git a/.conda/bin/install b/.conda/bin/install new file mode 100755 index 000000000..54917ed35 --- /dev/null +++ b/.conda/bin/install @@ -0,0 +1,30 @@ +#!/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 --remove channels defaults +conda config --add channels defaults +conda config --add channels conda-forge +conda config --set show_channel_urls true +conda install --yes --quiet conda-build +source deactivate diff --git a/.conda/bld.bat b/.conda/bld.bat new file mode 100644 index 000000000..c133a1154 --- /dev/null +++ b/.conda/bld.bat @@ -0,0 +1,10 @@ +:: NOTE: Windows not supported! + +"%PYTHON%" setup.py install +if errorlevel 1 exit 1 + +:: Add more build steps here, if they are necessary. + +:: See +:: http://docs.continuum.io/conda/build.html +:: for a list of environment variables that are set during the build process. diff --git a/.conda/build.sh b/.conda/build.sh new file mode 100755 index 000000000..f8132e5cf --- /dev/null +++ b/.conda/build.sh @@ -0,0 +1,18 @@ +#!/bin/bash + +if [[ "$OSTYPE" == "darwin"* ]]; then + export MACOSX_DEPLOYMENT_TARGET=10.9 +fi + +export CC=$(which clang) +export CXX=$(which clang++) + +# 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 + +# See +# http://docs.continuum.io/conda/build.html +# for a list of environment variables that are set during the build process. diff --git a/.conda/meta.yaml b/.conda/meta.yaml new file mode 100644 index 000000000..9f5cfc123 --- /dev/null +++ b/.conda/meta.yaml @@ -0,0 +1,93 @@ +package: + name: brainiak + version: {{ GIT_DESCRIBE_TAG }} + +about: + home: http://brainiak.org + license: Apache 2 + summary: 'Brain Imaging Analysis Kit' + license_family: APACHE + +source: + # git_url: https://github.com/brainiak/brainiak + # git_rev: master + path: ../ + +build: + # If this is a new build for the same version, increment the build + # number. If you do not include this key, it defaults to 0. + # number: 1 + 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 + +requirements: + build: + - python + - pip + - llvm + - cmake + - setuptools + - setuptools_scm + - mpich + - openmp + - cython + - mpi4py + - nitime + - numpy + - scikit-learn + - scipy !=1.0.0 + - theano + - pybind11 >=1.7 + - psutil + - nibabel + - typing + + run: + - python + - pip + - llvm + - mpich + - openmp + - cython + - mpi4py + - nitime + - numpy + - scikit-learn + - scipy !=1.0.0 + - theano + - pybind11 >=1.7 + - psutil + - nibabel + - typing + +test: + # Python imports + imports: + - brainiak + - brainiak.eventseg + - brainiak.factoranalysis + - brainiak.fcma + - brainiak.funcalign + - brainiak.hyperparamopt + - brainiak.reprsimil + - brainiak.searchlight + - brainiak.utils + commands: + - export CC=$(which clang) CXX=$(which clang++) && 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 + +# See +# http://docs.continuum.io/conda/build.html for +# more information about meta.yaml diff --git a/.travis.yml b/.travis.yml index 1dda25b66..7e4d5fcd4 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 + script: ./.conda/bin/build + + - os: osx + osx_image: xcode8 + install: ./.conda/bin/install + script: ./.conda/bin/build + install: - python3 -m pip install -U pip From 9a909a325c578c2bbc5b074605decf5c7a9c76da Mon Sep 17 00:00:00 2001 From: Daniel Suo Date: Thu, 1 Feb 2018 17:48:15 -0500 Subject: [PATCH 02/13] Add build file --- .conda/bin/build | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100755 .conda/bin/build diff --git a/.conda/bin/build b/.conda/bin/build new file mode 100755 index 000000000..2f4e42d05 --- /dev/null +++ b/.conda/bin/build @@ -0,0 +1,6 @@ +#!/usr/bin/env bash + +DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" + +export BRAINIAK_HOME=$DIR/../../ +~/miniconda3/bin/conda build $DIR/.. From 2f71e90be8053aec13102e0ea2fa4e757c609dc1 Mon Sep 17 00:00:00 2001 From: Daniel Suo Date: Thu, 1 Feb 2018 21:41:18 -0500 Subject: [PATCH 03/13] Fixing up dependency issues with Linux --- .conda/bin/docker | 6 ++++++ .conda/bin/{install => install-miniconda} | 0 .conda/build.sh | 5 +++-- .conda/meta.yaml | 7 +++++-- .travis.yml | 15 +++++++++++++-- 5 files changed, 27 insertions(+), 6 deletions(-) create mode 100755 .conda/bin/docker rename .conda/bin/{install => install-miniconda} (100%) 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 b/.conda/bin/install-miniconda similarity index 100% rename from .conda/bin/install rename to .conda/bin/install-miniconda diff --git a/.conda/build.sh b/.conda/build.sh index f8132e5cf..8f08bce7c 100755 --- a/.conda/build.sh +++ b/.conda/build.sh @@ -2,10 +2,11 @@ if [[ "$OSTYPE" == "darwin"* ]]; then export MACOSX_DEPLOYMENT_TARGET=10.9 + export CC=$(which clang) + export CXX=$(which clang++) fi -export CC=$(which clang) -export CXX=$(which clang++) +echo $PREFIX # Install pymanopt via pip because there isn't a conda package $PYTHON -m pip install pymanopt diff --git a/.conda/meta.yaml b/.conda/meta.yaml index 9f5cfc123..e2c2155a5 100644 --- a/.conda/meta.yaml +++ b/.conda/meta.yaml @@ -29,7 +29,8 @@ requirements: build: - python - pip - - llvm + - llvm # [osx] + - gcc # [linux] - cmake - setuptools - setuptools_scm @@ -78,7 +79,9 @@ test: - brainiak.searchlight - brainiak.utils commands: - - export CC=$(which clang) CXX=$(which clang++) && mpiexec -n 2 pytest $BRAINIAK_HOME + # Pytest on Linux gets quite upset if we don't remove pycache from the tests directory + - find $BRAINIAK_HOME/tests | grep pycache | xargs rm -rf # [linux] + - 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);' diff --git a/.travis.yml b/.travis.yml index 7e4d5fcd4..e6252c55c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -43,12 +43,23 @@ matrix: # Build and test conda packages - os: linux dist: trusty - install: ./.conda/bin/install + env: + - MINICONDA_URL="https://repo.continuum.io/miniconda" + - MINICONDA_FILE="Miniconda3-latest-Linux-x86_64.sh" + install: &install_miniconda + - curl -L "${MINICONDA_URL}/${MINICONDA_FILE}" -o ~/${MINICONDA_FILE} + - bash ~/$MINICONDA_FILE -b -u + - source ~/miniconda3/bin/activate root + - conda install --yes --quiet conda-build + - source deactivate script: ./.conda/bin/build - os: osx osx_image: xcode8 - install: ./.conda/bin/install + env: + - MINICONDA_URL="https://repo.continuum.io/miniconda" + - MINICONDA_FILE="Miniconda3-latest-MacOSX-x86_64.sh" + install: *install_miniconda script: ./.conda/bin/build install: From de71aa6a1338082464721c4a2a1ef5cce60ce6ce Mon Sep 17 00:00:00 2001 From: Daniel Suo Date: Thu, 1 Feb 2018 21:45:14 -0500 Subject: [PATCH 04/13] Clean up .travis.yml --- .travis.yml | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/.travis.yml b/.travis.yml index e6252c55c..f76252d9e 100644 --- a/.travis.yml +++ b/.travis.yml @@ -43,23 +43,12 @@ matrix: # Build and test conda packages - os: linux dist: trusty - env: - - MINICONDA_URL="https://repo.continuum.io/miniconda" - - MINICONDA_FILE="Miniconda3-latest-Linux-x86_64.sh" - install: &install_miniconda - - curl -L "${MINICONDA_URL}/${MINICONDA_FILE}" -o ~/${MINICONDA_FILE} - - bash ~/$MINICONDA_FILE -b -u - - source ~/miniconda3/bin/activate root - - conda install --yes --quiet conda-build - - source deactivate + install: ./.conda/bin/install-miniconda script: ./.conda/bin/build - os: osx osx_image: xcode8 - env: - - MINICONDA_URL="https://repo.continuum.io/miniconda" - - MINICONDA_FILE="Miniconda3-latest-MacOSX-x86_64.sh" - install: *install_miniconda + install: ./.conda/bin/install-miniconda script: ./.conda/bin/build install: From e539d57b611d47559731026911041ddec0d29dd5 Mon Sep 17 00:00:00 2001 From: Daniel Suo Date: Fri, 2 Feb 2018 14:32:13 -0500 Subject: [PATCH 05/13] Remove bld.bat; clear pycache before testing --- .conda/bld.bat | 10 ---------- .conda/meta.yaml | 3 +-- 2 files changed, 1 insertion(+), 12 deletions(-) delete mode 100644 .conda/bld.bat diff --git a/.conda/bld.bat b/.conda/bld.bat deleted file mode 100644 index c133a1154..000000000 --- a/.conda/bld.bat +++ /dev/null @@ -1,10 +0,0 @@ -:: NOTE: Windows not supported! - -"%PYTHON%" setup.py install -if errorlevel 1 exit 1 - -:: Add more build steps here, if they are necessary. - -:: See -:: http://docs.continuum.io/conda/build.html -:: for a list of environment variables that are set during the build process. diff --git a/.conda/meta.yaml b/.conda/meta.yaml index e2c2155a5..6e296094b 100644 --- a/.conda/meta.yaml +++ b/.conda/meta.yaml @@ -79,8 +79,7 @@ test: - brainiak.searchlight - brainiak.utils commands: - # Pytest on Linux gets quite upset if we don't remove pycache from the tests directory - - find $BRAINIAK_HOME/tests | grep pycache | xargs rm -rf # [linux] + - 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 From b9adfc2a95a58f6c9c224dee6a29886adb07b7ed Mon Sep 17 00:00:00 2001 From: Daniel Suo Date: Fri, 2 Feb 2018 18:05:59 -0500 Subject: [PATCH 06/13] Add contributing instructions --- CONTRIBUTING.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 71c35b6cb..0a63000c6 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -313,3 +313,17 @@ right to make releases. git tag --push twine upload dist/brainiak-.tar.gz + +6. Install Miniconda 3 if necessary:: + + ./.conda/bin/install-miniconda + +7. Create and test the Conda package:: + + ./.conda/bin/build + +8. Upload the built Conda package:: + + anaconda upload -u brainiak /path-to-miniconda3/conda-bld//brainiak--.tar.bz2 + +9. Repeat the process for desired operating systems and versions of Python. From dbb1cbeea74574dba17a85582a8130c36abd3bfd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mihai=20Capot=C4=83?= Date: Thu, 8 Feb 2018 11:11:27 -0800 Subject: [PATCH 07/13] Refactor and add docs --- .conda/bin/build | 11 +++++- .conda/build.sh | 4 -- .conda/meta.yaml | 84 ++++++++++++++-------------------------- CONTRIBUTING.rst | 34 +++++++++++----- README.rst | 92 ++++---------------------------------------- docs/index.rst | 1 + requirements-dev.txt | 7 +++- run-tests.sh | 1 + 8 files changed, 77 insertions(+), 157 deletions(-) diff --git a/.conda/bin/build b/.conda/bin/build index 2f4e42d05..2714131a2 100755 --- a/.conda/bin/build +++ b/.conda/bin/build @@ -3,4 +3,13 @@ DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" export BRAINIAK_HOME=$DIR/../../ -~/miniconda3/bin/conda build $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/build.sh b/.conda/build.sh index 8f08bce7c..63535aa96 100755 --- a/.conda/build.sh +++ b/.conda/build.sh @@ -13,7 +13,3 @@ $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 - -# See -# http://docs.continuum.io/conda/build.html -# for a list of environment variables that are set during the build process. diff --git a/.conda/meta.yaml b/.conda/meta.yaml index 6e296094b..67268c18e 100644 --- a/.conda/meta.yaml +++ b/.conda/meta.yaml @@ -1,22 +1,23 @@ +{% 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 }} + version: {{ GIT_DESCRIBE_TAG[1:] }} about: - home: http://brainiak.org - license: Apache 2 - summary: 'Brain Imaging Analysis Kit' - license_family: APACHE + home: {{ data.get('url') }} + license: {{ data.get('license') }} + summary: {{ data.get('description') }} source: - # git_url: https://github.com/brainiak/brainiak - # git_rev: master path: ../ build: - # If this is a new build for the same version, increment the build - # number. If you do not include this key, it defaults to 0. - # number: 1 number: {{ GIT_DESCRIBE_NUMBER }} script_env: @@ -24,60 +25,35 @@ build: # 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 - - pip - - llvm # [osx] - - gcc # [linux] - - cmake - setuptools - - setuptools_scm - - mpich + - pip - openmp - - cython - - mpi4py - - nitime - - numpy - - scikit-learn - - scipy !=1.0.0 - - theano - - pybind11 >=1.7 - - psutil - - nibabel - - typing + {% 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 - - pip - - llvm - - mpich - openmp - - cython - - mpi4py - - nitime - - numpy - - scikit-learn - - scipy !=1.0.0 - - theano - - pybind11 >=1.7 - - psutil - - nibabel - - typing + {% for req in data.get('install_requires', []) + if req not in conda_package_nonexistent -%} + - {{req}} + {% endfor %} test: - # Python imports - imports: - - brainiak - - brainiak.eventseg - - brainiak.factoranalysis - - brainiak.fcma - - brainiak.funcalign - - brainiak.hyperparamopt - - brainiak.reprsimil - - brainiak.searchlight - - brainiak.utils commands: - find $BRAINIAK_HOME/tests | grep pycache | xargs rm -rf - mpiexec -n 2 pytest $BRAINIAK_HOME @@ -89,7 +65,3 @@ test: requires: - pytest - numdifftools - -# See -# http://docs.continuum.io/conda/build.html for -# more information about meta.yaml diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0a63000c6..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 @@ -314,16 +330,14 @@ right to make releases. git tag --push twine upload dist/brainiak-.tar.gz -6. Install Miniconda 3 if necessary:: - ./.conda/bin/install-miniconda - -7. Create and test the Conda package:: +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:: + .conda/bin/build - anaconda upload -u brainiak /path-to-miniconda3/conda-bld//brainiak--.tar.bz2 +8. Upload the built Conda package (repeat command for all OSes and Python + versions); requires the ``anaconda-client`` Conda package:: -9. Repeat the process for desired operating systems and versions of Python. + anaconda upload -u brainiak \ + $CONDA_HOME/conda-bld//brainiak--.tar.bz2 diff --git a/README.rst b/README.rst index 3f5df2eb4..71f967029 100644 --- a/README.rst +++ b/README.rst @@ -20,93 +20,17 @@ 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 -======================== - -The Brain Imaging Analysis Kit is available on PyPI. You can install it (or -upgrade to the latest version) using the following command:: +Quickstart +========== - python3 -m pip install -U brainiak +If you have `Conda `_:: -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. + conda install -c brainiak brainiak -.. _issue #61: - https://github.com/brainiak/brainiak/issues/61 +Otherwise, or if you want to compile from source, install the requirements (see +docs/installation) and then install from PyPI:: -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. + python3 -m pip install brainiak Docker @@ -176,4 +100,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/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 fc1b18da5..c6654204c 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 From 9f32f2a4ede3ced6c9e9f9d0503558d9cee8c4f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mihai=20Capot=C4=83?= Date: Fri, 9 Feb 2018 09:37:08 -0800 Subject: [PATCH 08/13] Add installation.rst --- docs/installation.rst | 91 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/installation.rst diff --git a/docs/installation.rst b/docs/installation.rst new file mode 100644 index 000000000..6938aabd5 --- /dev/null +++ b/docs/installation.rst @@ -0,0 +1,91 @@ +============ +Installation +============ + +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. From 1b52f42664527fcac8f5fdd2479118d61e0d934c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mihai=20Capot=C4=83?= Date: Fri, 9 Feb 2018 10:13:01 -0800 Subject: [PATCH 09/13] Give priority to default Conda channel --- .conda/bin/install-miniconda | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/.conda/bin/install-miniconda b/.conda/bin/install-miniconda index 54917ed35..8817d81da 100755 --- a/.conda/bin/install-miniconda +++ b/.conda/bin/install-miniconda @@ -22,9 +22,7 @@ rm -f ~/${MINICONDA_FILE} echo "" echo "Configuring conda." source ~/miniconda3/bin/activate root -conda config --remove channels defaults -conda config --add channels defaults -conda config --add channels conda-forge +conda config --add channels conda-forge --add channels defaults conda config --set show_channel_urls true conda install --yes --quiet conda-build source deactivate From 66cade4fea623b8499b6334ccfbed44ed698fef4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mihai=20Capot=C4=83?= Date: Fri, 9 Feb 2018 15:10:33 -0800 Subject: [PATCH 10/13] Add conda-forge channel to instructions --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 2be1ef0e2..934d36d75 100644 --- a/README.rst +++ b/README.rst @@ -28,7 +28,7 @@ Quickstart If you have `Conda `_:: - conda install -c brainiak brainiak + conda install -c brainiak -c defaults -c conda-forge brainiak Otherwise, or if you want to compile from source, install the requirements (see docs/installation) and then install from PyPI:: From 835ffea1b9cfdf5f01c99ed4d47fa25a445baa01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mihai=20Capot=C4=83?= Date: Mon, 12 Feb 2018 16:15:40 -0800 Subject: [PATCH 11/13] Add note about Xcode --- README.rst | 4 +++- docs/installation.rst | 16 ++++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 934d36d75..329411a1f 100644 --- a/README.rst +++ b/README.rst @@ -31,10 +31,12 @@ If you have `Conda `_:: conda install -c brainiak -c defaults -c conda-forge brainiak Otherwise, or if you want to compile from source, install the requirements (see -docs/installation) and then install from PyPI:: +:doc:`installation`) and then install from PyPI:: python3 -m pip install brainiak +Note that we do not support Windows. + Docker ====== diff --git a/docs/installation.rst b/docs/installation.rst index 6938aabd5..45f312951 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -2,6 +2,22 @@ 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 ============ From 9b393b3e613e9acf6ab0b29e49f74dec16d46979 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mihai=20Capot=C4=83?= Date: Mon, 12 Feb 2018 16:23:45 -0800 Subject: [PATCH 12/13] Add news item --- docs/newsfragments/328.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 docs/newsfragments/328.feature 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. From 9619457bbfe20d614c06069ad77511b4215136b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mihai=20Capot=C4=83?= Date: Mon, 12 Feb 2018 17:33:58 -0800 Subject: [PATCH 13/13] No Sphinx syntax outside docs dir --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 329411a1f..0046e5fc4 100644 --- a/README.rst +++ b/README.rst @@ -31,7 +31,7 @@ If you have `Conda `_:: conda install -c brainiak -c defaults -c conda-forge brainiak Otherwise, or if you want to compile from source, install the requirements (see -:doc:`installation`) and then install from PyPI:: +`docs/installation`) and then install from PyPI:: python3 -m pip install brainiak