Skip to content

Commit

Permalink
Inform users 8.0 release is last one to support autotools (#819)
Browse files Browse the repository at this point in the history 
* Inform users 8.0 release is last one to support autotools

* Minor improvements to README and configure.ac message

Co-authored-by: Matthias Wolf <m+git@sushinara.net>
Co-authored-by: Pramod Kumbhar <pramod.kumbhar@epfl.ch>
  • Loading branch information
@alexsavulescu @matz-e @pramodk
3 people committed Jan 6, 2021
1 parent 9e12ff3 commit 8b0218b
Show file tree
Hide file tree
Showing 2 changed files with 110 additions and 64 deletions.
165 changes: 101 additions & 64 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,30 @@
[![Build Status](https://api.travis-ci.org/neuronsimulator/nrn.svg?branch=master)](https://travis-ci.org/neuronsimulator/nrn) [![Build Status](https://dev.azure.com/neuronsimulator/nrn/_apis/build/status/neuronsimulator.nrn?branchName=master)](https://dev.azure.com/neuronsimulator/nrn/_build/latest?definitionId=1&branchName=master) [![Actions Status](https://github.com/neuronsimulator/nrn/workflows/Windows%20Installer/badge.svg)](https://github.com/neuronsimulator/nrn/actions) [![Actions Status](https://github.com/neuronsimulator/nrn/workflows/NEURON%20CI/badge.svg)](https://github.com/neuronsimulator/nrn/actions)

# NEURON
NEURON is a simulator for models of neurons and networks of neuron.
See [http://neuron.yale.edu](http://neuron.yale.edu) for installers, source code,
documentation, tutorials, announcements of courses and conferences,
and a discussion forum.

## Building NEURON
## Installing Binary Distributions

NEURON provides binary installers for Linux, Mac and Windows platforms. You can find the latest installers for Mac and Windows [here](https://neuron.yale.edu/ftp/neuron/versions/alpha/). For Linux and Mac you can install the official Python 3 wheel with:

```
pip3 install neuron
```

## Installing from source

If you want to build the latest version from source, you can find instructions in the following. Currently we are supporting two build systems:

- [CMake](#build-cmake) (__recommended__)
- [Autotools](#build-autotools) (legacy, minimum support)

Note that starting with the 8.0 release, we recommend users to use CMake as the primary build system for NEURON. We would be grateful for any feedback or issues you encounter using the CMake-based build system. Please [report any issue here](https://github.com/neuronsimulator/nrn/issues) and we will be happy to help.

If you are using autotools, we highly recommend switching to CMake.

NEURON provided binary installers for Linux, Mac and Windows platform [here](https://neuron.yale.edu/ftp/neuron/versions/alpha/). If you want to build latest version from source, you can find instructions bellow.

### Build Dependencies

Expand All @@ -16,6 +33,7 @@ In order to build NEURON from source, following packages must be available:
- Bison
- Flex
- C/C++ compiler suite
- CMake 3.8 or Autotools

Following packages are optional (see build options):

Expand All @@ -24,58 +42,10 @@ Following packages are optional (see build options):
- MPI (for parallel)
- X11 (Linux) or XQuartz (MacOS) (for GUI)

### Build using Autotools

If you would like to have GUI support, you first need to install Interviews package available from GitHub [here](http://github.com/neuronsimulator/iv) or tarball provided [here](http://neuron.yale.edu/ftp/neuron/versions/alpha/). In case of git repository, first you need to run `build.sh` script to create the automake, autoconf, libtool generated files:

```bash
sh build.sh
```

And then run standard `configure`, `make` and `make install` steps to install Interviews:

```bash
./configure
make
make install
```

To build NEURON we have to use same steps as Interviews i.e. if source is obtained from the git repository, run `build.sh` script to create the automake, autoconf, libtool generated files:

```bash
sh build.sh
```

and then run standard `configure`, `make` and `make install` steps:

```bash
./configure
make
make install
```

If you want to customize build, particularly useful configure options are:


- `--prefix=/some/path` : Install in this location of your filesystem.
- `--without-x` : If the InterViews graphics library is not installed, disable GUI.
- `--with-iv=<prefix>/../iv` : If InterViews was not installed in <prefix>/../iv
- `--with-paranrn` : Parallel models on cluster computers using MPI
- `--with-nrnpython` : Use Python as an alternative interpreter (as well as the native HOC interpreter).
- `--with-nmodl-only` : Build nmodl only (in case of cross compiling)
- `--disable-rx3d` : Do not compile the cython translated 3-d rxd features


For more details see the [INSTALL.md](https://github.com/neuronsimulator/nrn/blob/master/INSTALL.md)
file.

For more installation information see: [https://neuron.yale.edu/neuron/download/getdevel](https://neuron.yale.edu/neuron/download/getdevel).

<a name="build-cmake"></a>
### Build using CMake

NEURON can now also be built and installed using [CMake build system](https://cmake.org/). Currently we are supporting two build systems i.e. Autoconf and CMake. In the future, based on the feedback from the community we will decide on switching to CMake build system. Therefore, we would be grateful for any feedback or issues you encounter using CMake based build system. Please [report an issue here](https://github.com/neuronsimulator/nrn/issues) and we will be happy to help.

One of the primary advantage of CMake based build system is integration with other projects like [Interviews](https://github.com/neuronsimulator/iv), [CoreNEURON](https://github.com/BlueBrain/CoreNeuron/), [NMODL](https://github.com/BlueBrain/nmodl/) etc. Such projects are now integrated into single CMake based build system and they can be installed together as shown below:
Starting with the 7.8.1 release, NEURON can be installed using the [CMake build system](https://cmake.org/). One of the primary advantages of a CMake-based build system is cross platform support and integration with other projects like [Interviews](https://github.com/neuronsimulator/iv), [CoreNEURON](https://github.com/BlueBrain/CoreNeuron/), [NMODL](https://github.com/BlueBrain/nmodl/) etc. These projects are now integrated into single a CMake-based build system and they can be installed together as shown below:


1. Clone latest version:
Expand All @@ -92,33 +62,41 @@ One of the primary advantage of CMake based build system is integration with oth
cd build
```

3. Run cmake with the appropriate options (see below for list of common options). \
A full list of options can be found in *nrn/CMakeLists.txt* . Defaults are shown in *nrn/cmake/BuildOptionDefaults.cmake*), \
3. If you are building on Cray systems with a GNU toolchain, you have to set following environmental variable:

```
export CRAYPE_LINK_TYPE=dynamic
```

4. Run `cmake` with the appropriate options (see below for a list of common options). \
A full list of options can be found in `nrn/CMakeLists.txt` and defaults are shown in `nrn/cmake/BuildOptionDefaults.cmake`. \
e.g. a bare-bones install:

```
cmake .. \
-DNRN_ENABLE_INTERVIEWS=OFF \
-DNRN_ENABLE_MPI=OFF \
-DNRN_ENABLE_RX3D=OFF
-DNRN_ENABLE_RX3D=OFF \
-DCMAKE_INSTALL_PREFIX=/path/to/install/directory
```

Note that if you are building on Cray system with GNU toolchain, you have to set following environmental variable **before** calling above CMake comamnd:

```
export CRAYPE_LINK_TYPE=dynamic
```

4. Build the code:
5. Build the code:

```
make -j
make install
```

6. Set PATH and PYTHONPATH environmental variables to use the installation:

```
export PATH=/path/to/install/directory/bin:$PATH
export PYTHONPATH=/path/to/install/directory/lib/python:$PYTHONPATH
```


Particularly useful CMake options are (use **ON** to enable and **OFF** to disable feature):

* **-DNRN\_ENABLE\_BINARY_SPECIAL=ON** : Build special as a binary instead of shell script
* **-DNRN\_ENABLE\_INTERVIEWS=OFF** : Disable Interviews (native GUI support)
* **-DNRN\_ENABLE\_PYTHON=OFF** : Disable Python support
* **-DNRN\_ENABLE\_MPI=OFF** : Disable MPI support for parallelization
Expand All @@ -127,10 +105,69 @@ Particularly useful CMake options are (use **ON** to enable and **OFF** to disab
* **-DNRN\_ENABLE\_TESTS=ON** : Enable unit tests
* **-DPYTHON\_EXECUTABLE=/python/binary/path** : Use provided Python binary to build Python interface
* **-DCMAKE_INSTALL_PREFIX=/install/dir/path** : Location for installing
* **-DCORENRN\_ENABLE\_NMODL=ON** : Use [NMODL](https://github.com/BlueBrain/nmodl/) instead of [MOD2C](https://github.com/BlueBrain/mod2c/) for code generation with CoreNEURON
* **-DCORENRN\_ENABLE\_NMODL=ON** : Use [NMODL](https://github.com/BlueBrain/nmodl/) instead of [MOD2C](https://github.com/BlueBrain/mod2c/) for code generation
with CoreNEURON
* **-DNRN\_ENABLE\_BINARY_SPECIAL=ON** : Build special as a binary instead of shell script


Please refer to [docs/cmake_doc/options.rst](docs/cmake_doc/options.rst) for more information on the CMake options.

<a name="build-autotools"></a>
### Build using Autotools

If you would like to have GUI support, you first need to install the Interviews package available from GitHub [here](http://github.com/neuronsimulator/iv) or the tarball provided [here](http://neuron.yale.edu/ftp/neuron/versions/alpha/). In case of the former, first you need to run `build.sh` script to create the automake, autoconf, and libtool generated files:

```bash
sh build.sh
```

And then run the standard `configure`, `make` and `make install` steps to install Interviews:

```bash
./configure --prefix=/path/to/install/directory
make
make install
```

To build NEURON we have to use the same steps as Interviews, i.e., if the source is obtained from the git repository, run `build.sh` script to create the automake, autoconf, and libtool generated files:

```bash
sh build.sh
```

and then run the standard `configure`, `make` and `make install` steps:

```bash
./configure --prefix=/path/to/install/directory
make
make install
```

You can set the following environmental variables to use the installation:

```bash
export PATH=/path/to/install/directory/<arch>/bin:$PATH # replace <arch> with x86_64 or other platform directory
export PYTHONPATH=/path/to/install/directory/lib/python:$PYTHONPATH
```


If you want to customize the build, particularly useful configure options are:


- `--prefix=/some/path` : Install in this location of your filesystem.
- `--without-x` : If the InterViews graphics library is not installed, disable GUI.
- `--with-iv=<prefix>/../iv` : If InterViews was not installed in <prefix>/../iv
- `--with-paranrn` : Parallel models on cluster computers using MPI
- `--with-nrnpython` : Use Python as an alternative interpreter (as well as the native HOC interpreter).
- `--with-nmodl-only` : Build nmodl only (in case of cross compiling)
- `--disable-rx3d` : Do not compile the cython translated 3-d rxd features


For additional documentation see the [INSTALL file](INSTALL.md)
file.

For more installation information see: [https://neuron.yale.edu/neuron/download/getdevel](https://neuron.yale.edu/neuron/download/getdevel).

## Developer documentation

Please refer to [docs/README.md](docs/README.md)
9 changes: 9 additions & 0 deletions configure.ac
View file
Original file line number Diff line number Diff line change
Expand Up @@ -704,3 +704,12 @@ AC_CONFIG_FILES([
fi

AC_OUTPUT

AC_MSG_WARN([
!!!
CMake is now the primary build system for installing NEURON from source.
Autotools support will be deprecated in future releases. As you are
using Autotools, we highly recommend switching to CMake as of now.
Please see the instructions in the README.md.
!!!
])

0 comments on commit 8b0218b

Please sign in to comment.