Skip to content
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
Copy link
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
Copy link
Contributor Author

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
Copy link
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
Copy link
Contributor

jougs left a comment

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

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.

Copy link
@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.

Copy link
@heplesser

heplesser Jan 5, 2017

Author Contributor

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


### Manual installation

The clang/clang++ compiler that ships with OSX/macOS does not support OpenMP

This comment has been minimized.

Copy link
@jougs

jougs Jan 4, 2017

Contributor

"OSX" -> "OS X"

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.

Copy link
@jougs

jougs Jan 4, 2017

Contributor

Insert "see the " in front of "INSTALL"

This comment has been minimized.

Copy link
@heplesser

heplesser Jan 5, 2017

Author Contributor

Done.


6. Compile by running `make`
6. Compile by running `make `

This comment has been minimized.

Copy link
@jougs

jougs Jan 4, 2017

Contributor

Why did you add the space?

This comment has been minimized.

Copy link
@heplesser

heplesser Jan 5, 2017

Author Contributor

Typo.


7. Install by running `make install`

8. Run tests by running `make installcheck

This comment has been minimized.

Copy link
@jougs

jougs Jan 4, 2017

Contributor

Missing closing back tick at end of line.

This comment has been minimized.

Copy link
@heplesser

heplesser Jan 5, 2017

Author Contributor

Added.

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.

Copy link
@jougs

jougs Jan 4, 2017

Contributor

Add space before backslash.

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.

Copy link
@jougs

jougs Jan 4, 2017

Contributor

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


### Virtual Machines

A virtual machine is a software that lets you use Linux in parallel to Windows.

This comment has been minimized.

Copy link
@jougs

jougs Jan 4, 2017

Contributor

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


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.

Copy link
@jougs

jougs Jan 4, 2017

Contributor

Please convert to"normal" Markdown links.

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.

Copy link
@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
Copy link
Contributor Author

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
Copy link

henriklinden commented Jan 5, 2017

@heplesser looks good to me!

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.

Copy link
@steffengraber

steffengraber Jan 6, 2017

Collaborator

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

This comment has been minimized.

Copy link
@heplesser

heplesser Jan 6, 2017

Author Contributor

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

Copy link
Contributor

jougs left a comment

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

execute 'brew info nest'

run `brew info nest`
3. To install nest, execute 'brew install nest'

This comment has been minimized.

Copy link
@jougs

jougs Jan 6, 2017

Contributor

Change single quotes to back ticks.

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.

Copy link
@jougs

jougs Jan 6, 2017

Contributor

Missing back tick at beginning of line.

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.

Copy link
@jougs

jougs Jan 6, 2017

Contributor

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

make -j4 # -j4 builds in parallel using 4 processes
make install
make installcheck

This comment has been minimized.

Copy link
@jougs

jougs Jan 6, 2017

Contributor

Add more indentation to render as code block.

@heplesser
Copy link
Contributor Author

heplesser commented Jan 6, 2017

@jougs Thanks! Should all be fixed now.

Copy link
Collaborator

steffengraber left a comment

👍 For me everything looks fine

Copy link
Contributor

jougs left a comment

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.

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.

Copy link
@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?

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.

Copy link
@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.

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.

Copy link
@jougs

jougs Jan 6, 2017

Contributor

Should be indented more to become code block.

make -j4 # -j4 builds in parallel using 4 processes
make install
make installcheck

This comment has been minimized.

Copy link
@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.

-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.

Copy link
@jougs

jougs Jan 6, 2017

Contributor

Should become code block

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.

Copy link
@jougs

jougs Jan 6, 2017

Contributor

Should become code block

@@ -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.

Copy link
@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.

Copy link
@heplesser

heplesser Jan 9, 2017

Author Contributor

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

@heplesser
Copy link
Contributor Author

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
Copy link
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
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
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

5 participants
You can’t perform that action at this time.