New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix #375 installation documentation update #615

Merged
merged 8 commits into from Jan 11, 2017

Conversation

@heplesser
Contributor

heplesser commented Jan 4, 2017

This PR updates the installation documentation in the INSTALL and installation.md files to make them ready for NEST 2.12. Some of the material there was really very dated.

This documentation should be tested on Linux and OSX machines, and for website-compatibility, so I assign a range of reviewers.

@espenhgn, could you also take a look and maybe add some info on macports?

@heplesser

This comment has been minimized.

Show comment
Hide comment
@heplesser

heplesser Jan 4, 2017

Contributor

@henriklinden I added some of the info you provided on NEST User recently. Would you mind taking a look at the updated instructions?

Contributor

heplesser commented Jan 4, 2017

@henriklinden I added some of the info you provided on NEST User recently. Would you mind taking a look at the updated instructions?

@espenhgn

This comment has been minimized.

Show comment
Hide comment
@espenhgn

espenhgn Jan 4, 2017

Contributor

In order to install NEST with macports on MacOS Sierra version 10.12.2 with support for OpenMPI and OpenMP I did the following:

# use macports to install dependencies
sudo port install gcc6 cmake gsl openmpi-default libtool python27 py27-cython py27-nose doxygen

# compilers
export CC=/opt/local/bin/gcc-mp-6
export CXX=/opt/local/bin/g++-mp-6

# path variables
export NESTBLD=$HOME/Repositories/nest-simulator-bld
export NESTSOURCES=$HOME/Repositories/nest-simulator
export NESTPREFIX=$HOME/.local/nest

# create build directory
mkdir $NESTBLD
cd $NESTBLD

# configure
cmake -DCMAKE_INSTALL_PREFIX:PATH=$NESTPREFIX \
      -Dwith-mpi=ON \
      -Dwith-python=ON \
      -DPYTHON_LIBRARY=/opt/local/lib/libpython2.7.dylib \
      -DPYTHON_INCLUDE_DIR=/opt/local/Library/Frameworks/Python.framework/Versions/2.7/include/python2.7 \
      -DCMAKE_C_COMPILER=$CC \
      -DCMAKE_CXX_COMPILER=$CXX \
      $NESTSOURCES

# compile and install
make
make install
make installcheck
Contributor

espenhgn commented Jan 4, 2017

In order to install NEST with macports on MacOS Sierra version 10.12.2 with support for OpenMPI and OpenMP I did the following:

# use macports to install dependencies
sudo port install gcc6 cmake gsl openmpi-default libtool python27 py27-cython py27-nose doxygen

# compilers
export CC=/opt/local/bin/gcc-mp-6
export CXX=/opt/local/bin/g++-mp-6

# path variables
export NESTBLD=$HOME/Repositories/nest-simulator-bld
export NESTSOURCES=$HOME/Repositories/nest-simulator
export NESTPREFIX=$HOME/.local/nest

# create build directory
mkdir $NESTBLD
cd $NESTBLD

# configure
cmake -DCMAKE_INSTALL_PREFIX:PATH=$NESTPREFIX \
      -Dwith-mpi=ON \
      -Dwith-python=ON \
      -DPYTHON_LIBRARY=/opt/local/lib/libpython2.7.dylib \
      -DPYTHON_INCLUDE_DIR=/opt/local/Library/Frameworks/Python.framework/Versions/2.7/include/python2.7 \
      -DCMAKE_C_COMPILER=$CC \
      -DCMAKE_CXX_COMPILER=$CXX \
      $NESTSOURCES

# compile and install
make
make install
make installcheck
@jougs

Thanks for updating the installation instructions. I still have some questions and suggestions for possible changes.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
NEST compiles and runs on most Unix-like operating systems.
The installation instructions here should work on recent versions of Ubuntu or
Debian, while additional instructions for
[OSX/macOS are given below](installation.md#macos).

This comment has been minimized.

@jougs

jougs Jan 4, 2017

Contributor

"OSX" -> "OS X", also more occurrences later.

Also, I think the link would look cleaner if the target was just written as (#macos). This would also allow to rename the file without changing its content (if that should ever be needed)

@jougs

jougs Jan 4, 2017

Contributor

"OSX" -> "OS X", also more occurrences later.

Also, I think the link would look cleaner if the target was just written as (#macos). This would also allow to rename the file without changing its content (if that should ever be needed)

This comment has been minimized.

@heplesser

heplesser Jan 5, 2017

Contributor

Fixed; removed file name also for all other internal links.

@heplesser

heplesser Jan 5, 2017

Contributor

Fixed; removed file name also for all other internal links.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
### Manual installation
The clang/clang++ compiler that ships with OSX/macOS does not support OpenMP

This comment has been minimized.

@jougs

jougs Jan 4, 2017

Contributor

"OSX" -> "OS X"

@jougs

jougs Jan 4, 2017

Contributor

"OSX" -> "OS X"

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
The installation instructions here should work on recent versions of Ubuntu or
Debian, while additional instructions for
[OSX/macOS are given below](installation.md#macos).
For more generic installation instructions, `INSTALL` file in the top source

This comment has been minimized.

@jougs

jougs Jan 4, 2017

Contributor

Insert "see the " in front of "INSTALL"

@jougs

jougs Jan 4, 2017

Contributor

Insert "see the " in front of "INSTALL"

This comment has been minimized.

@heplesser

heplesser Jan 5, 2017

Contributor

Done.

@heplesser

heplesser Jan 5, 2017

Contributor

Done.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
6. Compile by running `make`
6. Compile by running `make `

This comment has been minimized.

@jougs

jougs Jan 4, 2017

Contributor

Why did you add the space?

@jougs

jougs Jan 4, 2017

Contributor

Why did you add the space?

This comment has been minimized.

@heplesser

heplesser Jan 5, 2017

Contributor

Typo.

@heplesser

heplesser Jan 5, 2017

Contributor

Typo.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
7. Install by running `make install`
8. Run tests by running `make installcheck

This comment has been minimized.

@jougs

jougs Jan 4, 2017

Contributor

Missing closing back tick at end of line.

@jougs

jougs Jan 4, 2017

Contributor

Missing closing back tick at end of line.

This comment has been minimized.

@heplesser

heplesser Jan 5, 2017

Contributor

Added.

@heplesser

heplesser Jan 5, 2017

Contributor

Added.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
6. Configure and build NEST inside that directory:
cmake -DCMAKE_INSTALL_PREFIX:PATH=</install/path> \
-DCMAKE_C_COMPILER=gcc-6\

This comment has been minimized.

@jougs

jougs Jan 4, 2017

Contributor

Add space before backslash.

@jougs

jougs Jan 4, 2017

Contributor

Add space before backslash.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
computer. The LiveCD can be used in almost any computer and boots directly into
a complete Ubuntu system, which already has NEST, Python, and some analysis
tools installed.
The CD image is available on the [download page](download.md).

This comment has been minimized.

@jougs

jougs Jan 4, 2017

Contributor

Actually, we don't have live media anymore. Please remove this paragraph.

@jougs

jougs Jan 4, 2017

Contributor

Actually, we don't have live media anymore. Please remove this paragraph.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
### Virtual Machines
A virtual machine is a software that lets you use Linux in parallel to Windows.

This comment has been minimized.

@jougs

jougs Jan 4, 2017

Contributor

Replace "in parallel to" by "on top of"

@jougs

jougs Jan 4, 2017

Contributor

Replace "in parallel to" by "on top of"

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
A virtual machine is a software that lets you use Linux in parallel to Windows.
We recommend to use VirtualBox, which is free software and can be downloaded
from <http://www.virtualbox.org/>. Another popular virtual machine software is <http://www.vmware.com/>.

This comment has been minimized.

@jougs

jougs Jan 4, 2017

Contributor

Please convert to"normal" Markdown links.

@jougs

jougs Jan 4, 2017

Contributor

Please convert to"normal" Markdown links.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
from <http://www.virtualbox.org/>. Another popular virtual machine software is <http://www.vmware.com/>.
The easiest way to get started is to download the NEST LiveCD from the [download page](download.md)
and either just boot the CD image directly or install it into a virtual hard
disk.

This comment has been minimized.

@jougs

jougs Jan 4, 2017

Contributor

This information is outdated. We now have proper OVA images that can be directly imported by VM software.

@jougs

jougs Jan 4, 2017

Contributor

This information is outdated. We now have proper OVA images that can be directly imported by VM software.

@heplesser

This comment has been minimized.

Show comment
Hide comment
@heplesser

heplesser Jan 5, 2017

Contributor

@espenhgn Thank you for the info on MacPorts, I have integrated it.

@jougs I have integrated your suggestions (I stopped adding "done" comments eventually ...) and also tidied up in the "NEST 2.10 and earlier" section.

Contributor

heplesser commented Jan 5, 2017

@espenhgn Thank you for the info on MacPorts, I have integrated it.

@jougs I have integrated your suggestions (I stopped adding "done" comments eventually ...) and also tidied up in the "NEST 2.10 and earlier" section.

@henriklinden

This comment has been minimized.

Show comment
Hide comment
@henriklinden

henriklinden Jan 5, 2017

@heplesser looks good to me!

@heplesser looks good to me!

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
NEST compiles and runs on most Unix-like operating systems.
The installation instructions here should work on recent versions of Ubuntu or
Debian, while additional instructions for
[OS X/macOS are given below](#macos).

This comment has been minimized.

@steffengraber

steffengraber Jan 6, 2017

Contributor

The internal link to the section Mac OS X is #mac-os-x

@steffengraber

steffengraber Jan 6, 2017

Contributor

The internal link to the section Mac OS X is #mac-os-x

This comment has been minimized.

@heplesser

heplesser Jan 6, 2017

Contributor

Fixed. Based on this information I also updated the link to the NEST 2.10 documentation.

@heplesser

heplesser Jan 6, 2017

Contributor

Fixed. Based on this information I also updated the link to the NEST 2.10 documentation.

@jougs

Thanks for the changes. There are still some minor formating issues.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
execute 'brew info nest'
run `brew info nest`
3. To install nest, execute 'brew install nest'

This comment has been minimized.

@jougs

jougs Jan 6, 2017

Contributor

Change single quotes to back ticks.

@jougs

jougs Jan 6, 2017

Contributor

Change single quotes to back ticks.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
A more detailed up-to-date instruction for installation on OSX will
follow soon.
Options have to be appended, e.g. to install NEST with PyNEST run
brew install nest --with-python`.

This comment has been minimized.

@jougs

jougs Jan 6, 2017

Contributor

Missing back tick at beginning of line.

@jougs

jougs Jan 6, 2017

Contributor

Missing back tick at beginning of line.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
sudo port select ipython ipython27 # set default
3. Install dependencies via Homebrew
brew install gcc cmake gsl open-mpi libtool

This comment has been minimized.

@jougs

jougs Jan 6, 2017

Contributor

Add one more level of indentation to make this a code block.

@jougs

jougs Jan 6, 2017

Contributor

Add one more level of indentation to make this a code block.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
make -j4 # -j4 builds in parallel using 4 processes
make install
make installcheck

This comment has been minimized.

@jougs

jougs Jan 6, 2017

Contributor

Add more indentation to render as code block.

@jougs

jougs Jan 6, 2017

Contributor

Add more indentation to render as code block.

@heplesser

This comment has been minimized.

Show comment
Hide comment
@heplesser

heplesser Jan 6, 2017

Contributor

@jougs Thanks! Should all be fixed now.

Contributor

heplesser commented Jan 6, 2017

@jougs Thanks! Should all be fixed now.

@steffengraber

👍 For me everything looks fine

@jougs

Sorry, but I still found something to nag about :-(

To test the final markdown rendering using GirHub Flavored Markdown, I have written the following little bash function and found it pretty helpful:

function kd {
    firefox $(kramdown -i GFM $1 | base64 -w0 | cat <(echo -n "data:text/html;charset=UTF-8;base64,") -)
}

It takes a markdown file and opens the rendering in a new tab/window in firefox. Maybe it could also help you.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
A more detailed up-to-date instruction for installation on OSX will
follow soon.
Options have to be appended, e.g. to install NEST with PyNEST run
brew install nest `--with-python`.

This comment has been minimized.

@jougs

jougs Jan 6, 2017

Contributor

Why are the backticks only around the --with-python? I think the whole line is a command, or do I misinterpret this?

@jougs

jougs Jan 6, 2017

Contributor

Why are the backticks only around the --with-python? I think the whole line is a command, or do I misinterpret this?

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
export PATH=$PATH:$PREFIX/bin
export PYTHONPATH=$PREFIX/lib/pythonX.Y/site-packages:$PYTHONPATH
export PATH=$PATH:/install/path/bin
export PYTHONPATH=/install/path/lib/pythonX.Y/site-packages:$PYTHONPATH

This comment has been minimized.

@jougs

jougs Jan 6, 2017

Contributor

Add the following

The script /install/path/bin/nest_vars.sh can be sourced in .bashrc and will set these paths for you. This also allows to switch between NEST installations in a convenient manner.

@jougs

jougs Jan 6, 2017

Contributor

Add the following

The script /install/path/bin/nest_vars.sh can be sourced in .bashrc and will set these paths for you. This also allows to switch between NEST installations in a convenient manner.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
sudo port select ipython ipython27 # set default
3. Install dependencies via Homebrew
brew install gcc cmake gsl open-mpi libtool

This comment has been minimized.

@jougs

jougs Jan 6, 2017

Contributor

Should be indented more to become code block.

@jougs

jougs Jan 6, 2017

Contributor

Should be indented more to become code block.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
make -j4 # -j4 builds in parallel using 4 processes
make install
make installcheck

This comment has been minimized.

@jougs

jougs Jan 6, 2017

Contributor

Should be indented more to become code block. Alternatively, use triple back ticks throughout the document to denote code blocks.

@jougs

jougs Jan 6, 2017

Contributor

Should be indented more to become code block. Alternatively, use triple back ticks throughout the document to denote code blocks.

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
-DPYTHON_INCLUDE_DIR=/opt/local/Library/Frameworks/Python.framework/Versions/2.7/include/python2.7 \
-DCMAKE_C_COMPILER=/opt/local/bin/gcc-mp-6 \
-DCMAKE_CXX_COMPILER=/opt/local/bin/g++-mp-6 \
</path/to/NEST/src>

This comment has been minimized.

@jougs

jougs Jan 6, 2017

Contributor

Should become code block

@jougs

jougs Jan 6, 2017

Contributor

Should become code block

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
and save it under the name `Portfile` in an arbitrary directory
make -j4 # -j4 builds in parallel using 4 processes
make install
make installcheck

This comment has been minimized.

@jougs

jougs Jan 6, 2017

Contributor

Should become code block

@jougs

jougs Jan 6, 2017

Contributor

Should become code block

Show outdated Hide outdated extras/userdoc/md/documentation/installation.md
@@ -450,34 +499,3 @@ please try making NEST as follows:
env MACOSX_DEPLOYMENT_TARGET=10.5 make
Thanks to Harold Gutch for this hint.

This comment has been minimized.

@jougs

jougs Jan 6, 2017

Contributor

Can we remove this? If not, I guess we would have to add many more people here...

@jougs

jougs Jan 6, 2017

Contributor

Can we remove this? If not, I guess we would have to add many more people here...

This comment has been minimized.

@heplesser

heplesser Jan 9, 2017

Contributor

I removed the entire section, since this addressed problems that occurred with with OSX 10.5 very long ago.

@heplesser

heplesser Jan 9, 2017

Contributor

I removed the entire section, since this addressed problems that occurred with with OSX 10.5 very long ago.

@heplesser

This comment has been minimized.

Show comment
Hide comment
@heplesser

heplesser Jan 9, 2017

Contributor

@jougs Thank you for careful proof-reading! I hope all is fixed now. I also removed all in-paragraph line breaks, hope that will result in better formatting of normal text.

Contributor

heplesser commented Jan 9, 2017

@jougs Thank you for careful proof-reading! I hope all is fixed now. I also removed all in-paragraph line breaks, hope that will result in better formatting of normal text.

@espenhgn

This comment has been minimized.

Show comment
Hide comment
@espenhgn

espenhgn Jan 9, 2017

Contributor

@heplesser Looks good!

Contributor

espenhgn commented Jan 9, 2017

@heplesser Looks good!

@jougs

jougs approved these changes Jan 11, 2017

@heplesser heplesser removed request for abigailm and terhorstd Jan 11, 2017

@heplesser heplesser merged commit 1416cc2 into nest:master Jan 11, 2017

1 check was pending

continuous-integration/travis-ci/pr The Travis CI build is in progress
Details
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment