<html><body>
<p>1 new commit in yt:</p>
<p><a href="https://bitbucket.org/yt_analysis/yt/commits/80ec1ac414a7/">https://bitbucket.org/yt_analysis/yt/commits/80ec1ac414a7/</a> Changeset: 80ec1ac414a7 Branch: yt User: chummels Date: 2016-05-06 01:22:58+00:00 Summary: Merged in ngoldbaum/yt (pull request #2132)</p>
<p>[doc] Update install instructions to reflect changes in install script and build process. Closes #1196, Closes #1176, Closes #1094. Affected #: 1 file</p>
<p>diff -r cb216de0db743757a486ff0e90713812a6fb3e16 -r 80ec1ac414a7652791eed06469dc4104ff0c556b doc/source/installing.rst --- a/doc/source/installing.rst +++ b/doc/source/installing.rst @@ -18,26 +18,27 @@</p>
<pre>* If you do not have root access on your computer, are not comfortable managing
python packages, or are working on a supercomputer or cluster computer, you</pre>
<ul><li><p>will probably want to use the bash all-in-one installation script. This builds</p></li>
<li><p>Python, NumPy, Matplotlib, and yt from source to set up an isolated scientific</p></li>
<li><p>python environment inside of a single folder in your home directory. See</p></li>
<li><p>:ref:`install-script` for more details.</p></li></ul>
<p>+ will probably want to use the bash all-in-one installation script. This + creates a python environment using the `miniconda python + distrubtion <<a href="http://conda.pydata.org/miniconda.html">http://conda.pydata.org/miniconda.html</a>>`_ and the + `conda <<a href="http://conda.pydata.org/docs/">http://conda.pydata.org/docs/</a>>`_ package manager inside of a single + folder in your home directory. See :ref:`install-script` for more details.</p>
<pre>* If you use the `Anaconda <https://store.continuum.io/cshop/anaconda/>`_ python</pre>
<ul><li><p>distribution see :ref:`anaconda-installation` for details on how to install</p></li>
<li><p>yt using the ``conda`` package manager. Source-based installation from the</p></li>
<li><p>mercurial repository or via ``pip`` should also work under Anaconda. Note that</p></li>
<li><p>this is currently the only supported installation mechanism on Windows.</p></li></ul>
<p>+ distribution and already have ``conda`` installed, see + :ref:`anaconda-installation` for details on how to install yt using the + ``conda`` package manager. Note that this is currently the only supported + installation mechanism on Windows.</p>
<p>-* If you already have a scientific python software stack installed on your</p>
<ul><li><p>computer and are comfortable installing python packages,</p></li></ul>
<p>+* If you want to build a development version of yt or are comfortable with + compilers and know your way around python packaging,</p>
<pre>:ref:`source-installation` will probably be the best choice. If you have set
up python using a source-based package manager like `Homebrew
<http://brew.sh>`_ or `MacPorts <http://www.macports.org/>`_ this choice will</pre>
<ul><li><p>let you install yt using the python installed by the package manager. Similarly</p></li>
<li><p>for python environments set up via Linux package managers so long as you</p></li>
<li><p>have the necessary compilers installed (e.g. the ``build-essentials``</p></li>
<li><p>package on Debian and Ubuntu).</p></li></ul>
<p>+ let you install yt using the python installed by the package + manager. Similarly, this will also work for python environments set up via + Linux package managers so long as you have the necessary compilers installed + (e.g. the ``build-essentials`` package on Debian and Ubuntu).</p>
<pre>.. note::
See `Parallel Computation</pre>
<p>@@ -53,19 +54,21 @@</p>
<pre>Before you install yt, you must decide which branch (i.e. version) of the code
you prefer to use:
</pre>
<p>-* ``yt`` — The most up-to-date <strong>development</strong> version with the most current features but sometimes unstable (yt-3.x) -* ``stable`` — The latest stable release of yt-3.x -* ``yt-2.x`` — The latest stable release of yt-2.x +* ``yt`` — The most up-to-date <strong>development</strong> version with the most current + features but sometimes unstable (the development version of the next ``yt-3.x`` + release). +* ``stable`` — The latest stable release of ``yt-3.x``. +* ``yt-2.x`` — The last stable release of ``yt-2.x``.</p>
<p>-If this is your first time using the code, we recommend using ``stable``, -unless you specifically need some piece of brand-new functionality only -available in ``yt`` or need to run an old script developed for ``yt-2.x``. -There were major API and functionality changes made in yt after version 2.7 -in moving to version 3.0. For a detailed description of the changes -between versions 2.x (e.g. branch ``yt-2.x``) and 3.x (e.g. branches ``yt`` and -``stable``) see :ref:`yt3differences`. Lastly, don't feel like you're locked -into one branch when you install yt, because you can easily change the active -branch by following the instructions in :ref:`switching-between-yt-versions`. +If this is your first time using the code, we recommend using ``stable``, unless +you specifically need some piece of brand-new functionality only available in +``yt`` or need to run an old script developed for ``yt-2.x``. There were major +API and functionality changes made in yt for version 3.0. For a detailed +description of the changes between versions 2.x (e.g. branch ``yt-2.x``) and 3.x +(e.g. branches ``yt`` and ``stable``) see :ref:`yt3differences`. Lastly, don't +feel like you're locked into one branch when you install yt, because you can +easily change the active branch by following the instructions in +:ref:`switching-between-yt-versions`.</p>
<pre>.. _install-script:
</pre>
<p>@@ -74,9 +77,8 @@</p>
<pre>Because installation of all of the interlocking parts necessary to install yt
itself can be time-consuming, yt provides an all-in-one installation script</pre>
<p>-which downloads and builds a fully-isolated Python + NumPy + Matplotlib + HDF5 + -Mercurial installation. Since the install script compiles yt's dependencies from -source, you must have C, C++, and optionally Fortran compilers installed. +which downloads and builds a fully-isolated installation of Python that includes +NumPy, Matplotlib, H5py, Mercurial, and yt.</p>
<pre>The install script supports UNIX-like systems, including Linux, OS X, and most
supercomputer and cluster environments. It is particularly suited for deployment</pre>
<p>@@ -94,30 +96,62 @@</p>
<pre>^^^^^^^^^^^^^^^^^^^^^^^^^^
To get the installation script for the ``stable`` branch of the code,</pre>
<p>-download it from: +download it using the following command:</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>wget <a href="http://bitbucket.org/yt_analysis/yt/raw/stable/doc/install_script.sh">http://bitbucket.org/yt_analysis/yt/raw/stable/doc/install_script.sh</a></p></li></ul>
<p>+ $ wget <a href="http://bitbucket.org/yt_analysis/yt/raw/stable/doc/install_script.sh">http://bitbucket.org/yt_analysis/yt/raw/stable/doc/install_script.sh</a></p>
<p>-If you wish to install a different version of yt (see -:ref:`above <branches-of-yt>`), replace ``stable`` with the appropriate -branch name (e.g. ``yt``, ``yt-2.x``) in the path above to get the correct -install script. – -By default, the bash install script will install an array of items, but there -are additional packages that can be downloaded and installed (e.g. SciPy, enzo, -etc.). The script has all of these options at the top of the file. You should be -able to open it and edit it without any knowledge of bash syntax. To execute -it, run: +If you do not have ``wget``, the following should also work:</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>bash install_script.sh</p></li></ul>
<p>+ $ curl -OL <a href="http://bitbucket.org/yt_analysis/yt/raw/stable/doc/install_script.sh">http://bitbucket.org/yt_analysis/yt/raw/stable/doc/install_script.sh</a> + +If you wish to install a different version of yt (see :ref:`branches-of-yt`), +replace ``stable`` with the appropriate branch name (e.g. ``yt``, ``yt-2.x``) in +the path above to get the correct install script. + +By default, the bash install script will create a python environment based on +the `miniconda python distrubtion <<a href="http://conda.pydata.org/miniconda.html">http://conda.pydata.org/miniconda.html</a>>`_, +and will install yt's dependencies using the `conda +<<a href="http://conda.pydata.org/docs/">http://conda.pydata.org/docs/</a>>`_ package manager. To avoid needing a +compilation environment to run the install script, yt itself will also be +installed using `conda`. + +If you would like to customize your yt installation, you can edit the values of +several variables that are defined at the top of the script. + +If you would like to build yt from source, you will need to edit the install +script and set ``INST_YT_SOURCE=1`` near the top. This will clone a copy of the +yt mercurial repository and build yt form source. The default is +``INST_YT_SOURCE=0``, which installs yt from a binary conda package. + +The install script can also build python and all yt dependencies from source. To +switch to this mode, set ``INST_CONDA=0`` at the top of the install script. If +you choose this mode, you must also set ``INST_YT_SOURCE=1``. + +In addition, you can tell the install script to download and install some +additional packages --- currently these include +`PyX <<a href="http://pyx.sourceforge.net/">http://pyx.sourceforge.net/</a>>`_, the `Rockstar halo +finder <<a href="http://arxiv.org/abs/1110.4372">http://arxiv.org/abs/1110.4372</a>>`_, `SciPy <<a href="https://www.scipy.org/">https://www.scipy.org/</a>>`_, +`Astropy <<a href="http://www.astropy.org/">http://www.astropy.org/</a>>`_, and the necessary dependencies for +:ref:`unstructured mesh rendering <unstructured_mesh_rendering>`. The script has +all of the options for installing optional packages near the top of the +file. You should be able to open it and edit it without any knowledge of bash +syntax. For example, to install scipy, change ``INST_SCIPY=0`` to +``INST_SCIPY=1``. + +To execute the install script, run: + +.. code-block:: bash + + $ bash install_script.sh</p>
<pre>Because the installer is downloading and building a variety of packages from</pre>
<p>-source, this will likely take a while (e.g. 20 minutes), but you will get -updates of its status at the command line throughout. +source, this will likely take a few minutes, especially if you have a slow +internet connection or have ``INST_CONDA=0`` set. You will get updates of its +status at the command prompt throughout.</p>
<pre>If you receive errors during this process, the installer will provide you
with a large amount of information to assist in debugging your problems. The</pre>
<p>@@ -127,26 +161,63 @@</p>
<pre>potentially figure out what went wrong. If you have problems, though, do not
hesitate to :ref:`contact us <asking-for-help>` for assistance.
</pre>
<p>+If the install script errors out with a message about being unable to import the +python SSL bindings, this means that the Python built by the install script was +unable to link against the OpenSSL library. This likely means that you installed +with ``INST_CONDA=0`` on a recent version of OSX, or on a cluster that has a +very out of date installation of OpenSSL. In both of these cases you will either +need to install OpenSSL yourself from the system package manager or consider +using ``INST_CONDA=1``, since conda-based installs can install the conda package +for OpenSSL. +</p>
<pre>.. _activating-yt:
Activating Your Installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Once the installation has completed, there will be instructions on how to set up</pre>
<p>-your shell environment to use yt by executing the activate script. You must -run this script in order to have yt properly recognized by your system. You can -either add it to your login script, or you must execute it in each shell session -prior to working with yt. +your shell environment to use yt. + +Activating Conda-based installs (``INST_CONDA=1``) +"""""""""""""""""""""""""""""""""""""""""""""""""" + +For conda-based installs, you will need to ensure that the installation's +``yt-conda/bin`` directory is prepended to your ``PATH`` environment variable. + +For Bash-style shells, you can use the following command in a terminal session +to temporarily activate the yt installation:</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>source <yt installation directory>/bin/activate</p></li></ul>
<p>+ $ export PATH=/path/to/yt-conda/bin:$PATH + +and on csh-style shells: + +.. code-block:: csh + + $ setenv PATH /path/to/yt-conda/bin:$PATH + +If you would like to permanently activate yt, you can also update the init file +appropriate for your shell and OS (e.g. .bashrc, .bash_profile, .cshrc, .zshrc) +to include the same command. + +Activating source-based installs (``INST_CONDA=0``) +""""""""""""""""""""""""""""""""""""""""""""""""""" + +For this installation method, you must run an ``activate`` script to activate +the yt environment in a terminal session. You must run this script in order to +have yt properly recognized by your system. You can either add it to your login +script, or you must execute it in each shell session prior to working with yt. + +.. code-block:: bash + + $ source <yt installation directory>/bin/activate</p>
<pre>If you use csh or tcsh as your shell, activate that version of the script:
.. code-block:: bash
</pre>
<ul><li><p>source <yt installation directory>/bin/activate.csh</p></li></ul>
<p>+ $ source <yt installation directory>/bin/activate.csh</p>
<pre>If you don't like executing outside scripts on your computer, you can set
the shell variables manually. ``YT_DEST`` needs to point to the root of the</pre>
<p>@@ -166,14 +237,21 @@</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>yt update</p></li></ul>
<p>+ $ yt update</p>
<p>-Additionally, if you want to make sure you have the latest dependencies -associated with yt and update the codebase simultaneously, type this: +Additionally, if you ran the install script with ``INST_CONDA=0`` and want to +make sure you have the latest dependencies associated with yt and update the +codebase simultaneously, type this:</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>yt update --all</p></li></ul>
<p>+ $ yt update --all + +If you ran the install script with ``INST_CONDA=1`` and want to update your dependencies, run: + +.. code-block:: bash + + $ conda update --all</p>
<pre>.. _removing-yt:
</pre>
<p>@@ -192,35 +270,26 @@</p>
<pre>Installing yt Using Anaconda
++++++++++++++++++++++++++++
</pre>
<p>-Perhaps the quickest way to get yt up and running is to install it using the -`Anaconda Python Distribution <<a href="https://store.continuum.io/cshop/anaconda/">https://store.continuum.io/cshop/anaconda/</a>>`_, -which will provide you with a easy-to-use environment for installing Python -packages. – -If you do not want to install the full anaconda python distribution, you can -install a bare-bones Python installation using miniconda. To install miniconda, -visit <a href="http://repo.continuum.io/miniconda/">http://repo.continuum.io/miniconda/</a> and download ``Miniconda-latest-…`` -script for your platform and system architecture. Next, run the script, e.g.: – -.. code-block:: bash –</p>
<ul><li><p>bash Miniconda-latest-Linux-x86_64.sh</p></li></ul>
<p>–</p>
<pre>For both the Anaconda and Miniconda installations, make sure that the Anaconda
``bin`` directory is in your path, and then issue:
.. code-block:: bash
</pre>
<ul><li><p>conda install yt</p></li></ul>
<p>+ $ conda install yt</p>
<pre>which will install stable branch of yt along with all of its dependencies.
</pre>
<p>+.. _nightly-conda-builds: + +Nightly Conda Builds +^^^^^^^^^^^^^^^^^^^^ +</p>
<pre>If you would like to install latest development version of yt, you can download
it from our custom anaconda channel:
.. code-block:: bash
</pre>
<ul><li><p>conda install -c <a href="http://use.yt/with_conda/">http://use.yt/with_conda/</a> yt</p></li></ul>
<p>+ $ conda install -c <a href="http://use.yt/with_conda/">http://use.yt/with_conda/</a> yt</p>
<pre>New packages for development branch are built after every pull request is
merged. In order to make sure you are running latest version, it's recommended</pre>
<p>@@ -228,28 +297,26 @@</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>conda update -c <a href="http://use.yt/with_conda/">http://use.yt/with_conda/</a> yt</p></li></ul>
<p>+ $ conda update -c <a href="http://use.yt/with_conda/">http://use.yt/with_conda/</a> yt</p>
<pre>Location of our channel can be added to ``.condarc`` to avoid retyping it during
each *conda* invocation. Please refer to `Conda Manual
<http://conda.pydata.org/docs/config.html#channel-locations-channels>`_ for
detailed instructions.
</pre>
<p>+.. _conda-source-build:</p>
<p>-Obtaining Source Code -^^^^^^^^^^^^^^^^^^^^^ +Building yt from Source For Conda-based Installs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^</p>
<p>-There are two ways to get the yt source code when using an Anaconda -installation. – -Option 1: – -Ensure that you have all build dependencies installed in your current +First, ensure that you have all build dependencies installed in your current</p>
<pre>conda environment:
.. code-block:: bash
</pre>
<ul><li><p>conda install cython mercurial sympy ipython h5py matplotlib</p></li></ul>
<p>+ $ conda install cython mercurial sympy ipython matplotlib + +In addition, you will need a C compiler installed.</p>
<pre>.. note::
</pre>
<p>@@ -260,87 +327,124 @@</p>
<pre> .. code-block:: bash
</pre>
<ul><li><p>export CONDA_DIR=$(python -c ‘import sys; print(sys.executable.split("/bin/python")[0])’)</p></li>
<li><p>conda create -y -n py27 python=2.7 mercurial</p></li>
<li><p>ln -s ${CONDA_DIR}/envs/py27/bin/hg ${CONDA_DIR}/bin</p></li></ul>
<p>+ $ export CONDA_DIR=$(python -c ‘import sys; print(sys.executable.split("/bin/python")[0])’) + $ conda create -y -n py27 python=2.7 mercurial + $ ln -s ${CONDA_DIR}/envs/py27/bin/hg ${CONDA_DIR}/bin</p>
<pre>Clone the yt repository with:
.. code-block:: bash
</pre>
<ul><li><p>hg clone <a href="https://bitbucket.org/yt_analysis/yt">https://bitbucket.org/yt_analysis/yt</a></p></li></ul>
<p>+ $ hg clone <a href="https://bitbucket.org/yt_analysis/yt">https://bitbucket.org/yt_analysis/yt</a></p>
<pre>Once inside the yt directory, update to the appropriate branch and</pre>
<p>-run ``setup.py``. For example, the following commands will allow you +run ``setup.py develop``. For example, the following commands will allow you</p>
<pre>to see the tip of the development branch.
.. code-block:: bash
</pre>
<ul><li><p>hg up yt</p></li>
<li><p>python setup.py develop</p></li></ul>
<p>+ $ hg pull + $ hg update yt + $ python setup.py develop</p>
<pre>This will make sure you are running a version of yt corresponding to the
most up-to-date source code.
</pre>
<p>-Option 2: +.. _rockstar-conda:</p>
<p>-Recipes to build conda packages for yt are available at -<a href="https://github.com/conda/conda-recipes">https://github.com/conda/conda-recipes</a>. To build the yt conda recipe, first -clone the conda-recipes repository +Rockstar Halo Finder for Conda-based installations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The easiest way to set rockstar up in a conda-based python envrionment is to run +the install script with both ``INST_CONDA=1`` and ``INST_ROCKSTAR=1``. + +If you want to do this manually, you will need to follow these +instructions. First, clone Matt Turk's fork of rockstar and compile it:</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>git clone <a href="https://github.com/conda/conda-recipes">https://github.com/conda/conda-recipes</a></p></li></ul>
<p>+ $ hg clone <a href="https://bitbucket.org/MatthewTurk/rockstar">https://bitbucket.org/MatthewTurk/rockstar</a> + $ cd rockstar + $ make lib</p>
<p>-Then navigate to the repository root and invoke ``conda build``: +Next, copy `librockstar.so` into the `lib` folder of your anaconda installation:</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>cd conda-recipes</p></li>
<li><p>conda build ./yt/</p></li></ul>
<p>+ $ cp librockstar.so /path/to/anaconda/lib</p>
<p>-Note that building a yt conda package requires a C compiler. +Finally, you will need to recompile yt to enable the rockstar interface. Clone a +copy of the yt mercurial repository (see :ref:`conda-source-build`), or navigate +to a clone that you have already made, and do the following: + +.. code-block:: bash + + $ cd /path/to/yt-hg + $ ./clean.sh + $ echo /path/to/rockstar > rockstar.cfg + $ python setup.py develop + +Here ``/path/to/yt-hg`` is the path to your clone of the yt mercurial repository +and ``/path/to/rockstar`` is the path to your clone of Matt Turk's fork of +rockstar. + +Finally, to actually use rockstar, you will need to ensure the folder containing +`librockstar.so` is in your LD_LIBRARY_PATH: + +.. code-block:: bash + + $ export LD_LIBRARY_PATH=/path/to/anaconda/lib + +You should now be able to enter a python session and import the rockstar +interface: + +.. code-block:: python + + >>> from yt.analysis_modules.halo_finding.rockstar import rockstar_interface + +If this python import fails, then you have not installed rockstar and yt's +rockstar interface correctly.</p>
<pre>.. _windows-installation:
Installing yt on Windows
^^^^^^^^^^^^^^^^^^^^^^^^
</pre>
<p>-Installation on 64-bit Microsoft Windows platforms is supported using Anaconda (see -:ref:`anaconda-installation`). Also see :ref:`windows-developing` for details on how to build yt -from source in Windows. +Installation on 64-bit Microsoft Windows platforms is supported using Anaconda +(see :ref:`anaconda-installation`). Also see :ref:`windows-developing` for +details on how to build yt from source in Windows.</p>
<pre>.. _source-installation:
</pre>
<p>-Installing yt Using pip or from Source -++++++++++++++++++++++++++++++++++++++ +Installing yt Using ``pip`` or From Source +++++++++++++++++++++++++++++++++++++++++++ + +.. note:: + + If you wish to install yt from source in a conda-based installation of yt, + see :ref:`conda-source-build`.</p>
<pre>To install yt from source, you must make sure you have yt's dependencies</pre>
<p>-installed on your system. +installed on your system. Right now, the dependencies to build yt from +source include:</p>
<p>-If you use a Linux OS, use your distro's package manager to install these yt -dependencies on your system: +- ``mercurial`` +- A C compiler such as ``gcc`` or ``clang`` +- ``Python 2.7``, ``Python 3.4``, or ``Python 3.5``</p>
<p>— ``HDF5`` — ``zeromq`` — ``sqlite`` — ``mercurial`` – -Then install the required Python packages with ``pip``: +In addition, building yt from source requires several python packages +which can be installed with ``pip``:</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>$ pip install numpy matplotlib cython h5py nose sympy</p></li></ul>
<p>+ $ pip install numpy matplotlib cython sympy</p>
<p>-If you're using IPython notebooks, you can install its dependencies -with ``pip`` as well: +You may also want to install some of yt's optional dependencies, including +``jupyter``, ``h5py`` (which in turn depends on the HDF5 library), ``scipy``, or +``astropy``,</p>
<p>-.. code-block:: bash –</p>
<ul><li><p>$ pip install ipython[notebook]</p></li></ul>
<p>– -From here, you can use ``pip`` (which comes with ``Python``) to install the latest -stable version of yt: +From here, you can use ``pip`` (which comes with ``Python``) to install the +latest stable version of yt:</p>
<pre>.. code-block:: bash
</pre>
<p>@@ -353,46 +457,30 @@</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>hg clone <a href="https://bitbucket.org/yt_analysis/yt">https://bitbucket.org/yt_analysis/yt</a></p></li>
<li><p>cd yt</p></li>
<li><p>hg update yt</p></li>
<li><p>python setup.py install --user --prefix=</p></li></ul>
<p>+ $ hg clone <a href="https://bitbucket.org/yt_analysis/yt">https://bitbucket.org/yt_analysis/yt</a> + $ cd yt + $ hg update yt + $ python setup.py install --user --prefix=</p>
<pre>.. note::
</pre>
<ul><li><p>If you maintain your own user-level python installation separate from the OS-level python</p></li>
<li><p>installation, you can leave off ``--user --prefix=``, although you might need</p></li>
<li><p>``sudo`` depending on where python is installed. See `This StackOverflow</p></li>
<li><p>discussion</p></li></ul>
<p>+ If you maintain your own user-level python installation separate from the + OS-level python installation, you can leave off ``--user --prefix=``, although + you might need ``sudo`` depending on where python is installed. See `This + StackOverflow discussion</p>
<pre> <http://stackoverflow.com/questions/4495120/combine-user-with-prefix-error-with-setup-py-install>`_
if you are curious why ``--prefix=`` is neccessary on some systems.
</pre>
<p>-.. note:: –</p>
<ul><li><p>yt requires version 18.0 or higher of ``setuptools``. If you see</p></li>
<li><p>error messages about this package, you may need to update it. For</p></li>
<li><p>example, with pip via</p></li></ul>
<p>–</p>
<ul><li><p>.. code-block:: bash</p></li></ul>
<p>–</p>
<ul><li><p>pip install --upgrade setuptools</p></li></ul>
<p>–</p>
<ul><li><p>or your preferred method. If you have ``distribute`` installed, you</p></li>
<li><p>may also see error messages for it if it's out of date. You can</p></li>
<li><p>update with pip via</p></li></ul>
<p>–</p>
<ul><li><p>.. code-block:: bash</p></li></ul>
<p>–</p>
<ul><li><p>pip install --upgrade distribute</p></li></ul>
<p>–</p>
<ul><li><p>or via your preferred method.</p></li></ul>
<p>– –</p>
<pre>This will install yt into a folder in your home directory
(``$HOME/.local/lib64/python2.7/site-packages`` on Linux,
``$HOME/Library/Python/2.7/lib/python/site-packages/`` on OSX) Please refer to
the ``setuptools`` documentation for the additional options.
</pre>
<p>+If you are unable to locate the ``yt`` executable (i.e. ``yt version`` failes), +then you likely need to add the ``$HOME/.local/bin`` (or the equivalent on your +OS) to your PATH. Some linux distributions do not include this directory in the +default search path. +</p>
<pre>If you choose this installation method, you do not need to run any activation
script since this will install yt into your global python environment.
</pre>
<p>@@ -401,15 +489,35 @@</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>hg clone <a href="https://bitbucket.org/yt_analysis/yt">https://bitbucket.org/yt_analysis/yt</a></p></li>
<li><p>cd yt</p></li>
<li><p>hg update yt</p></li>
<li><p>python setup.py develop --user --prefix=</p></li></ul>
<p>+ $ hg clone <a href="https://bitbucket.org/yt_analysis/yt">https://bitbucket.org/yt_analysis/yt</a> + $ cd yt + $ hg update yt + $ python setup.py develop --user --prefix=</p>
<pre>As above, you can leave off ``--user --prefix=`` if you want to install yt into the default
package install path. If you do not have write access for this location, you
might need to use ``sudo``.
</pre>
<p>+Build errors with ``setuptools`` or ``distribute`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Building yt requires version 18.0 or higher of ``setuptools``. If you see error +messages about this package, you may need to update it. For example, with pip +via + +.. code-block:: bash + + $ pip install --upgrade setuptools + +or your preferred method. If you have ``distribute`` installed, you may also see +error messages for it if it's out of date. You can update with pip via + +.. code-block:: bash + + $ pip install --upgrade distribute + +or via your preferred method. +</p>
<pre>Keeping yt Updated via Mercurial
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
</pre>
<p>@@ -424,7 +532,7 @@</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>yt update</p></li></ul>
<p>+ $ yt update</p>
<pre>This will detect that you have installed yt from the mercurial repository, pull
any changes from Bitbucket, and then recompile yt if necessary.</pre>
<p>@@ -439,7 +547,7 @@</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>yt --help</p></li></ul>
<p>+ $ yt --help</p>
<pre>If this works, you should get a list of the various command-line options for
yt, which means you have successfully installed yt. Congratulations!</pre>
<p>@@ -453,21 +561,57 @@</p>
<pre>.. _switching-between-yt-versions:
</pre>
<p>-Switching versions of yt: yt-2.x, yt-3.x, stable, and dev ---------------------------------------------------------- +Switching versions of yt: ``yt-2.x``, ``stable``, and ``yt`` branches +---------------------------------------------------------------------</p>
<p>-With the release of version 3.0 of yt, development of the legacy yt 2.x series -has been relegated to bugfixes. That said, we will continue supporting the 2.x -series for the foreseeable future. This makes it easy to use scripts written -for older versions of yt without substantially updating them to support the -new field naming or unit systems in yt version 3. +Here we explain how to switch between different development branches of yt.</p>
<p>-Currently, the yt-2.x codebase is contained in a named branch in the yt -mercurial repository. Thus, depending on the method you used to install -yt, there are different instructions for switching versions. +If You Installed yt Using the Bash Install Script ++++++++++++++++++++++++++++++++++++++++++++++++++</p>
<p>-If You Installed yt Using the Installer Script -++++++++++++++++++++++++++++++++++++++++++++++ +The instructions for how to switch between branches depend on whether you ran +the install script with ``INST_YT_SOURCE=0`` (the default) or +``INST_YT_SOURCE=1``. You can determine which option you used by inspecting the +output: + +.. code-block:: bash + + $ yt version + +If the output from this command looks like: + +.. code-block:: none + + The current version and changeset for the code is: + + --- + Version = 3.2.3 + --- + +i.e. it does not refer to a specific changeset hash, then you originally chose +``INST_YT_SOURCE=0``. + +On the other hand, if the output from ``yt version`` looks like: + +.. code-block:: none + + The current version and changeset for the code is: + + --- + Version = 3.3-dev + Changeset = d8eec89b2c86 (yt) tip + --- + +i.e. it refers to a specific changeset in the yt mercurial repository, then +you installed using ``INST_YT_SOURCE=1``. + +Conda-based installs (``INST_YT_SOURCE=0``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this case you can either install one of the nightly conda builds (see :ref:`nightly-conda-builds`), or you can follow the instructions above to build yt from source under conda (see :ref:`conda-source-build`). + +Source-based installs (``INST_YT_SOURCE=1``) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^</p>
<pre>You already have the mercurial repository, so you simply need to switch
which version you're using. Navigate to the root of the yt mercurial</pre>
<p>@@ -476,9 +620,9 @@</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>cd yt-<machine>/src/yt-hg</p></li>
<li><p>hg update <desired-version></p></li>
<li><p>python setup.py develop</p></li></ul>
<p>+ $ cd yt-<machine>/src/yt-hg + $ hg update <desired-version> + $ python setup.py develop</p>
<pre>Valid versions to jump to are described in :ref:`branches-of-yt`.
</pre>
<p>@@ -494,8 +638,8 @@</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>pip uninstall yt</p></li>
<li><p>hg clone <a href="https://bitbucket.org/yt_analysis/yt">https://bitbucket.org/yt_analysis/yt</a></p></li></ul>
<p>+ $ pip uninstall yt + $ hg clone <a href="https://bitbucket.org/yt_analysis/yt">https://bitbucket.org/yt_analysis/yt</a></p>
<pre>Now, to switch between versions, you need to navigate to the root of
the mercurial yt repository. Use mercurial to</pre>
<p>@@ -503,9 +647,9 @@</p>
<pre>.. code-block:: bash
</pre>
<ul><li><p>cd yt</p></li>
<li><p>hg update <desired-version></p></li>
<li><p>python setup.py install --user --prefix=</p></li></ul>
<p>+ $ cd yt + $ hg update <desired-version> + $ python setup.py install --user --prefix=</p>
<pre>Valid versions to jump to are described in :ref:`branches-of-yt`).</pre>
<p>Repository URL: <a href="https://bitbucket.org/yt_analysis/yt/">https://bitbucket.org/yt_analysis/yt/</a></p>
<p>—</p>
<p>This is a commit notification from bitbucket.org. You are receiving this because you have the service enabled, addressing the recipient of this email.</p>
<img src="http://link.bitbucket.org/wf/open?upn=ll4ctv0L-2ByeRZFC1LslHcg6aJmnQ70VruLbmeLQr27BLctNt2C6h8LeWbjD-2FspYgZm0WvCdMdeODh3YVG5SIP4oWXxFmEdh3mDU0c2v38Rh9b5-2FcwqslXkI23TH-2BBoaRGSyBHtGMVAHd7VH-2Blsq2sOyd6bb7-2BwYFY743688RvU5HUQoCBLgSNHc6D1nF-2B9PQ8hTUQeIy0B-2By3nrE-2FflIiwYe7uuesVAqPuwiOkRIYIc-3D" alt="" width="1" height="1" border="0" style="height:1px !important;width:1px !important;border-width:0 !important;margin-top:0 !important;margin-bottom:0 !important;margin-right:0 !important;margin-left:0 !important;padding-top:0 !important;padding-bottom:0 !important;padding-right:0 !important;padding-left:0 !important;"/>
</body></html>