INSTALL

********************************************************************************
Lmod the lua based module system can be installed with:


   Note: Lmod requires Lua 5.1 or 5.2 or 5.3

         ***** Lua 5.0 or 4.0 will NOT work. *****


A) You must install lua first.  You have two choices:

      1) You can download the latest lua version from  the same place you got
         Lmod and install lua-X.X.X.tar.gz file.  It contains the lua command,
         lua library and other lua packages that Lmod requires.

  OR:

      2) Use the package system for your OS to install the following packages.
         This is the list is for Ubuntu 8.04.  It may be quite different with
         other Linux distributions or different OS

            liblua5.1-0
            liblua5.1-0-dev
            liblua5.1-filesystem-dev
            liblua5.1-filesystem0
            liblua5.1-posix-dev
            liblua5.1-posix0
            lua5.1

      Note; Centos may require looking the EPEL repo.  At TACC we install the
      following rpms;

            $ rpm -qa | grep lua

            lua-posix-5.1.7-1.el6.x86_64
            lua-5.1.4-4.1.el6.x86_64
            lua-filesystem-1.4.2-1.el6.x86_64
            lua-devel-5.1.4-4.1.el6.x86_64


  OR:
      You can use luarocks to install either luaposix and/or luafilesystem.

         $ luarocks install luaposix; luarocks install luafilesystem

      Then you have to make the lua packages installed by luarocks to be known
      by lua.  On our Centos system, Lua knowns about the following for *.lua
      files:

        $ lua -e 'print(package.path)'
        ./?.lua;/usr/share/lua/5.1/?.lua;/usr/share/lua/5.1/?/init.lua;/usr/lib64/lua/5.1/?.lua;/usr/lib64/lua/5.1/?/init.lua;

      and the following for shared libraries:

        $ lua -e 'print(package.cpath)'
        ./?.so;/usr/lib64/lua/5.1/?.so;/usr/lib64/lua/5.1/loadall.so;

      Where as luarocks can put them somewhere else.  You can see where
      luarocks puts things by running:

          $ luarocks path

      Assuming that luarocks has installed things in its default location (/usr/local/...)
      then you'll need to do:

         LUAROCKS_PREFIX=/usr/local
         export LUA_PATH="$LUAROCKS_PREFIX/share/lua/5.1/?.lua;$LUAROCKS_PREFIX/share/lua/5.1/?/init.lua;;"
         export LUA_CPATH="$LUAROCKS_PREFIX/lib/lua/5.1/?.so;;"

      Please change LUAROCKS_PREFIX to match your site.  The exporting of LUA_PATH and LUA_CPATH
      must be done before any module commands.


B) Now with version 5.+ of Lmod, it is now very important that sites with large
   modulefile installations build system spider cache files. In the
   contrib/BuildSystemCacheFile directory is an example script that shows how
   to build a cache file.  It also touches a file called "system.txt".  Whatever
   the name of this file, Lmod uses this file to know that the spider cache is
   up-to-date.

   Lmod uses the spider cache file as a replacement for walking the directory tree
   to find all modulefiles in your MODULEPATH.  This means that Lmod only knows
   about system modules that are found in the spider cache.  Lmod won't know about
   any system modules that are not in this cache.  (Personal module files are
   always found).  It turns out that reading a single file is much faster than
   walking the directory tree.

   Sites running Lmod have three choices:

      1) Do not create a spider cache for system modules.  This will work fine as
         long as the number of modules is not too large.  You will know when it
         is time to start building a cache file when you start getting complains
         how long it take to do any module commands.

      2) If you have a formal proceedure for installing packages on your system
         then I recommend you do the following.  Have the install proceedure run
         the createSystemCache.sh file.  This will create file called "system.txt"
         which marks the time that the system was last updated, so Lmod knows that
         the cache is still good.

      3) Or you can create a script (say createSystemCache.sh) that runs every 30
         mins.  This way the cache file is up-to-date.  No new module will be
         unknown for more 30 mins.  Assuming that you are going to store the cache file
         in /opt/moduleData/cacheDir and the timestamp is in /opt/moduleData/system.txt.
         Please create the following script:

            $ cd /opt/moduleData
            $ cat > createSystemCache.sh
            CACHE_LOCATION=/opt/moduleData
            LMOD_DIR=<path_to_the_command_spider>
            MODULEPATH=<Your site's default MODULEPATH>

            $LMOD_DIR/update_lmod_system_cache_files -t $CACHE_LOCATION/system.txt -d $CACHE_LOCATION/cacheDir $MODULEPATH
            ^D

         Please modify the top three environment variables to match your site.
         Then you will have to add createSystemCache.sh to your crontab.


      4) There are two ways to specify how cache directories and timestep files are
         specified.  You can use "--with-spiderCacheDir=dirs" and
         "--with-updateSystemFn=file" to specify one or more directories with a
         single timestamp file.  If you have multiple directories with multiple
         timestamp files you can use "--with-spiderCacheDescript=file" where the
         contents of the "file" is:

             cacheDir1:timestamp1
             cacheDir2:timestamp2

         lines starting with '#' and blank lines are ignored.



C) The program "lua" must be in your path before installing "Lmod".  The
   configure script won't install lmod without it.


   $ ./configure --prefix=/PATH/TO/LMOD/PARENT_DIR

     Install options:

      --prefix=/usr/local
         This will cause the "make install" to create /usr/local/lmod
         and /usr/local/lmod/version with a symlink /usr/local/lmod/lmod
         pointing to "version".

      --with-module-root-path=/PATH/TO/MODULEFILE/PARENT
         If you use the "Core" directory for Core modules, "Compiler" for compiler
         dependent module and MPI for MPI dependent modules then you may wish to
         define the env. var MODULEPATH_ROOT through this configure option.

      --with-spiderCacheDir=dirs
      --with-updateSystemFn=file
      --with-spiderCacheDescript=file
         These configure options are how Lmod knows about the spider cache file
         See Letter (B) for more details.  This is important!!!

      --with-duplicatePaths=ans
         Allow duplicates in path like variables (PATH, LD_LIBRARY_PATH, etc).
         Sites new to Lmod should allow for duplicate.  Sites that have used Lmod
         for a while should test to see if allowing duplicates leads to different
         behaviour for their users programs.


D) As an example here is my configuration line:


     ./configure --prefix=/opt/apps --with-spiderCacheDir=/opt/moduleData/cacheDir \
                 --with-updateSystemFn=/opt/moduleData/system.txt

   The system spider cache will stored in /opt/moduleData/cacheDir.
   And the system update file will be in /opt/moduleData/system.txt

E) In the init directory there are "profile.in" and "cshrc.in" templates.  The
   path to lua will automatically be generated.  The templates assume that your
   modulefiles are located in @PREFIX@/modulefiles/$LMOD_sys and
   @PREFIX@/modulefiles/Core, where @PREFIX@ is the path specified on the
   ./configure --prefix command


   *****************************************************************************
   Obviously you will want to modify the profile.in and cshrc.in files to suit
   your system.
   *****************************************************************************

F) There are two ways to install Lmod

      $ make pre-install

   or

      $ make install

   Most site will want to do "make install".  If you do:

      ./configure --prefix=/opt/apps

   Then "make pre-install" and "make install" will install the package in:
   "/opt/apps/lmod/5.0" or whatever version of Lmod you are installing.

   The install target does two more things:

      1) It installs the zsh tab completions function in a system location such
         as /usr/share/zsh/site-functions.
      2) It makes the sym-link between version and "lmod".

         /opt/apps/lmod/lmod => /opt/apps/lmod/5.0



G) You can write your module files in either lua or TCL.  Modulefiles with the lua
   extension are obviously have lua code and the one without are treated as TCL.
   The syntax of the lua modulefiles are similar but not the same.  Lua module
   commands are written as functions.  So in TCL its:

       setenv        MKL_DIR         /opt/local/intel/mkl
       prepend-path  LD_LIBRARY_PATH /opt/local/intel/lib
       append-path   PATH            /opt/local/intel/bin

   In lua it is:

       setenv(      "MKL_DIR",         "/opt/local/intel/mkl")
       prepend_path("LD_LIBRARY_PATH", "/opt/local/intel/lib")
       append_path( "PATH",            "/opt/local/intel/bin")

   Please notice that the dashes in the TCL syntax is replaced with underscores.

   So in general lua uses a function call and text literals such as MKL_DIR must
   be surrounded by quotes.  The TCL commands that have a dash such as append-path
   change to append_path in lua.

   *****************************************************************************
   Module files written in TCL have no extension where as lua module files have
   a .lua extension
   *****************************************************************************

   So the module for the MKL module above would be named "mkl" as a TCL module
   file and "mkl.lua" if it is written in lua.

H) The bash used on Redhat, Centos, Fedora, etc (but not Debian, Ubuntu)
   compiles bash with having a system file read during an interactive shell.
   We at TACC patch bash to always read a system bashrc file.  See
   contrib/bash_patch for our patch file.  You will want to modify it for
   your site.

I) If you are using "SitePackage.lua", you will need to register your functions
   with the sandbox_registration function.  See Contrib/SitePackage for more
   details.


J) If you wish to track module usage and do not put extra calls in your modulefiles,
   then please look in contrib/hook for an example on how to do it.


K) Join the lmod-users mailing list at:

      https://lists.sourceforge.net/lists/listinfo/lmod-users

   Please use this forum to ask questions.


Thanks for using Lmod.

R. McLay