Add some documentation. (#168)

Start documentation effort.

* address comments.

* add paragraph intro.

* change the location of the configuration.

README.md

@@ -1,3 +1,161 @@
+# The BlueBrain Spack Deployment
+
+Official documentation [below](#-spack).
+For the development documentation of the deployment stack, see
+[`deploy/README.md`](deploy/README.md).
+
+## Building software with Spack at BlueBrain
+
+On BB5, clone this repository to get started using Spack.
+The following commands are a good way to get started:
+
+ $ git clone https://github.com/BlueBrain/spack.git
+ $ . spack/share/spack/setup-env.sh
+ $ spack spec -I spykfunc|head -n 15
+ Input spec
+ --------------------------------
+  - spykfunc
+
+ Concretized
+ --------------------------------
+  - [email protected]%[email protected] arch=linux-rhel7-x86_64
+  - ^[email protected]%[email protected]~cxx~debug~fortran+hl~mpi+pic+shared~szip~threadsafe arch=linux-rhel7-x86_64
+  - ^[email protected]%[email protected]+optimize+pic+shared arch=linux-rhel7-x86_64
+  - ^[email protected]%[email protected]~boost build_type=RelWithDebInfo ~mpi arch=linux-rhel7-x86_64
+  - ^[email protected]%[email protected]~doc+ncurses+openssl+ownlibs~qt arch=linux-rhel7-x86_64
+  - ^[email protected]%[email protected]~symlinks~termlib arch=linux-rhel7-x86_64
+  - ^[email protected]%[email protected] arch=linux-rhel7-x86_64
+  - ^[email protected]%[email protected]+systemcerts arch=linux-rhel7-x86_64
+  - ^[email protected]%[email protected]+cpanm patches=0eac10ed90aeb0459ad8851f88081d439a4e41978e586ec743069e8b059370ac +shared+threads arch=linux-rhel7-x86_64
+
+Here we see all the software that would be required to build one program of
+the circuit building workflow.
+The leading `-` sign in the output signifies that this particular piece of
+software would have to be built from scratch.
+To reduce the amount of time spent compiling the same software, we can
+configure Spack to use centrally build packages on BB5:
+
+ $ mkdir -p ~/.spack
+ $ ln -s /gpfs/bbp.cscs.ch/apps/hpc/jenkins/config/*.yaml ~/.spack
+ $ export INSTALL_PATH=$HOME/software
+
+The configuration thus set up uses the environment variable `INSTALL_PATH`
+as the installation directory for packages.
+With the above setup, any packages installed can be found in `~/software`.
+Every call to Spack reads this environment variable, temporarily changing
+it is a good way to test changes.
+
+After adding the correct setup, the dependency graph of our software to
+install has changed significantly:
+
+ $ spack spec -I spykfunc|head -n 15
+ Input spec
+ --------------------------------
+  - spykfunc
+
+ Concretized
+ --------------------------------
+ [+] [email protected]%[email protected] arch=linux-rhel7-x86_64
+ [^] ^[email protected]%[email protected]~cxx~debug~fortran+hl~mpi+pic+shared~szip~threadsafe arch=linux-rhel7-x86_64
+ [^] ^[email protected]%[email protected]+optimize+pic+shared arch=linux-rhel7-x86_64
+ [^] ^[email protected]%[email protected]~boost build_type=RelWithDebInfo ~mpi arch=linux-rhel7-x86_64
+ [^] ^[email protected]_191-b12%[email protected] arch=linux-rhel7-x86_64
+ [^] ^[email protected]%[email protected] build_type=RelWithDebInfo ~mpi~python arch=linux-rhel7-x86_64
+ [+] ^[email protected]%[email protected]+atomic+chrono~clanglibcpp cxxstd=default +date_time~debug+exception+filesystem+graph~icu+iostreams+locale+log+math~mpi+multithreaded~numpy patches=2ab6c72d03dec6a4ae20220a9dfd5c8c572c5294252155b85c6874d97c323199 ~pic+program_options~python+random+regex+serialization+shared+signals~singlethreaded+system~taggedlayout+test+thread+timer~versionedlayout+wave arch=linux-rhel7-x86_64
+ [+] ^[email protected]%[email protected]~doc+ncurses+openssl+ownlibs~qt arch=linux-rhel7-x86_64
+ [^] ^[email protected]%[email protected] patches=22a56c05830b2e40dffbcbbc70cd2e95c006e13cb4da867f1b7e0d6292ff6618 arch=linux-rhel7-x86_64
+
+This tells us that all required software is either installed in an upstream
+database or provided as external packages in the package database (`[^]`
+and `[+]`, respectively).
+
+To see all installed packages available through the central installations
+directly, use:
+
+ $ spack find -lv|&head
+ ==> 265 installed packages
+ -- linux-rhel7-x86_64 / [email protected] -------------------------------
+ s26d2n5 [email protected] build_type=Release +parquet+python
+ ocjfhxp [email protected] build_type=Release +parquet+python
+ figbvwx [email protected]
+ py26izr [email protected]
+ v6f6e33 [email protected]+gold~libiberty+nls~plugins
+ j4xbdil [email protected]
+ o4mvxg2 [email protected]+atomic+chrono~clanglibcpp cxxstd=default +date_time~debug+exception+filesystem+graph~icu+iostreams+locale+log+math~mpi+multithreaded~numpy patches=2ab6c72d03dec6a4ae20220a9dfd5c8c572c5294252155b85c6874d97c323199 ~pic+program_options~python+random+regex+serialization+shared+signals~singlethreaded+system~taggedlayout+test+thread+timer~versionedlayout+wave
+ lnnxkhm [email protected]+shared
+
+These packages act like locally installed packages, only that you will not
+be able to uninstall them.
+Spack has access to the full dependency graph of the packages above, and
+environments will be set accordingly.
+The configuration of upstream package databases can be found in
+`~/.spack/upsreams.yaml`.
+Additional packages are installed and available as external software, where
+Spack will trim the dependency tree and only consider the external package
+without any sub-dependencies.
+The information for external packages is stored in
+`~/.spack/packages.yaml`, and can also be printed on the command line:
+
+ $ spack config get packages|&grep -C 1 paths:|tail -n 20
+ --
+  util-macros:
+  paths:
+  [email protected]: /gpfs/bbp.cscs.ch/apps/hpc/jenkins/deploy/tools/2018-12-19/linux-rhel7-x86_64/gcc-6.4.0/util-macros-1.19.1-et5doh3u6t
+ --
+  valgrind:
+  paths:
+  [email protected] +boost~mpi+only64bit+ubsan: /gpfs/bbp.cscs.ch/apps/hpc/jenkins/deploy/tools/2018-12-19/linux-rhel7-x86_64/gcc-6.4.0/valgrind-3.13.0-z5rpvffayd
+ --
+  xz:
+  paths:
+  [email protected]: /usr
+ --
+  zeromq:
+  paths:
+  [email protected] +libsodium: /gpfs/bbp.cscs.ch/apps/hpc/jenkins/deploy/external-libraries/2019-01-04/linux-rhel7-x86_64/gcc-6.4.0/zeromq-4.2.5-qvzt3welbs
+ --
+  zlib:
+  paths:
+  [email protected] +optimize+pic+shared: /gpfs/bbp.cscs.ch/apps/hpc/jenkins/deploy/external-libraries/2019-01-04/linux-rhel7-x86_64/gcc-6.4.0/zlib-1.2.11-w43e56tzqj
+
+
+## Managing Centrally Built Modules and Packages
+
+Centrally build modules can be made available by sourcing the following
+script:
+
+ $ . /gpfs/bbp.cscs.ch/apps/hpc/jenkins/config/modules.sh
+ $ module avail|&tail
+
+  /gpfs/bbp.cscs.ch/apps/hpc/jenkins/deploy/applications/2018-12-19/modules/tcl/linux-rhel7-x86_64
+ functionalizer/3.11.0 py-bluepyopt/1.6.56/python2
+ neurodamus/hippocampus/python3 py-bluepyopt/1.6.56/python3
+ neurodamus/master/python3 py-efel/3.0.22/python2
+ neurodamus/plasticity/python3 py-efel/3.0.22/python3
+ neurodamus/plasticity/python3-knl spykfunc/0.12.0/python3
+ parquet-converters/0.3 steps/3.3.0/python3/parallel
+ py-bluepymm/0.6.38/python2 synapsetool/0.3.2/parallel
+ py-bluepymm/0.6.38/python3 touchdetector/4.3.3
+
+The output above shows the `applications` category of modules, which are
+generated from centrally build packages.
+To update the version of any of these modules, edit the corresponding YAML
+configuration:
+
+ $ vim spack/deploy/packages/bbp-packages.yaml
+
+Commit the changes and file a pull request on Github.
+Jenkins will build the additional software required, with all output
+available in a separate directory:
+
+ $ ls /gpfs/bbp.cscs.ch/apps/hpc/jenkins/pulls/165
+ config deploy mirror spack
+
+Software packages and modules should be updated upon pull request merge and
+a nightly basis.
+The `config` directory contains the same configuration files as the regular
+deployment and can be used instead.
+
 # <img src="https://cdn.rawgit.com/spack/spack/develop/share/spack/logo/spack-logo.svg" width="64" valign="middle" alt="Spack"/> Spack
 
 [![Build Status](https://travis-ci.org/spack/spack.svg?branch=develop)](https://travis-ci.org/spack/spack)

deploy/README.md

@@ -9,7 +9,7 @@ Spack.
 * [Deployment Description](#deployment-workflow)
 * [Pull Request Building Description](#pull-request-workflow)
 
-###### CREDIT : Based on [spack-packagelist](https://github.com/epfl-scitas/spack-packagelist)
+**Credit:** Based on [spack-packagelist](https://github.com/epfl-scitas/spack-packagelist)
 
 ## Spec Generation
 

deploy/deploy.lib

@@ -467,6 +467,19 @@ copy_user_configuration() {
  echo "MODULEPATH=\"\${MODULEPATH}\${MODULEPATH:+:}${modpath}\"" >> ${target}/modules.sh
  done
  echo "export MODULEPATH" >> ${target}/modules.sh
+
+ cat << EOF >> "${target}/config.yaml"
+config:
+ install_tree: \$INSTALL_PATH/install
+ source_cache: \$INSTALL_PATH/.cache
+ module_roots:
+ tcl: \$INSTALL_PATH/modules/tcl
+ build_stage:
+ - \$tempdir
+ - \$INSTALL_PATH/.stage
+ install_path_scheme: '\${ARCHITECTURE}/\${COMPILERNAME}-\${COMPILERVER}/\${PACKAGE}-\${VERSION}-\${HASH:6}'
+ build_jobs: 36
+EOF
 }
 
 copy_modules() {

sysconfig/bb5/users/config.yaml

@@ -1,10 +1,10 @@
 config:
- install_tree: $SOFTS_DIR_PATH/install
- source_cache: $SOFTS_DIR_PATH/.cache
+ install_tree: $INSTALL_PATH/install
+ source_cache: $INSTALL_PATH/.cache
  module_roots:
- tcl: $SOFTS_DIR_PATH/modules/tcl
+ tcl: $INSTALL_PATH/modules/tcl
  build_stage:
  - $tempdir
- - $SOFTS_DIR_PATH/.stage
+ - $INSTALL_PATH/.stage
  install_path_scheme: '${ARCHITECTURE}/${COMPILERNAME}-${COMPILERVER}/${PACKAGE}-${VERSION}-${HASH:6}'
  build_jobs: 36