Installing Modules on Windows
*****************************

This document is an overview of building and installing Modules on a
Windows platform.


Requirements
============

Modules consists of one Tcl script so to run it from a user shell the
only requirement is to have a working version of "tclsh" (version 8.5
or later) available on your system. "tclsh" is a part of Tcl.

A specific distribution zipball is provided to install Modules on a
Windows platform. Content of this distribution zipball is ready for
use and does not require a specific build step. All scripts and
documentation found in this zipball are pre-built so there is no
specific tools are required to install Modules from the Windows-
specific distribution zipball.


Installation instructions
=========================

1. Install a Tcl binary distribution for Windows like ActiveTcl or
   Magicsplat Tcl/Tk for Windows. Follow instructions provided with
   the chosen distribution to install it.

2. Once installed, verify that the "tclsh" command is correctly found
   in defined "PATH" by typing the following command from a Windows
   "cmd" shell ("windows" string should be obtained as result):

      > echo puts $tcl_platform(platform) | tclsh
      windows

3. Download Modules specific distribution zipball for Windows from
   SourceForge or GitHub. Such distribution archives are available for
   Modules release starting version "4.5.0" and can be distinguished
   from the source tarball by the "-win" suffix in their name.

4. Unpack downloaded zip file then enter deflated directory and
   execute the "INSTALL.bat" script file found in it. This script
   installs files by default in "C:\Program Files\Environment
   Modules\" directory and adds the "bin" directory in this
   installation location to the system-wide "PATH" environment
   variable.

   If you use Powershell Core on Windows, please use the
   "INSTALL_PWSH.bat" instead. It won't add the "bin" directory to the
   system-wide "PATH" environment variable because the "module"
   command will interfere with Powershell's "module" keyword.

Note:

  "INSTALL.bat" and "INSTALL_PWSH.bat" scripts may require to be run
  with administrator rights to perform installation correctly.

5. Once installed, verify that the "module" command is correctly
   found. If you used the "INSTALL.bat" script, the commands should be
   in the defined "PATH". Verify by typing the following command from
   a Windows "cmd" shell:

      > module -V
      Modules Release 5.5.0 (2024-11-11)

   If your used the "INSTALL_PWSH.bat" script, the environment has to
   be initialized first. Verify by typing the following commands from
   a Windows "cmd" shell:

      > call "C:\Program Files\Environment Modules\init\cmd.cmd"
      > module -V
      Modules Release 5.5.0 (2024-11-11)

   And the following commands from a Windows "pwsh" shell:

      > . "C:\Program Files\Environment Modules\init\pwsh.ps1"
      > envmodule --version
      Modules Release 5.5.0 (2024-11-11)

Installation location can be adapted by running the "INSTALL.bat" and
"INSTALL_PWSH.bat" scripts from a "cmd" console shell and passing
desired installation target as argument. For instance to install
Modules in "C:\EnvironmentModules" directory:

   > INSTALL.bat C:\EnvironmentModules

For PowerShell, you may adapt profile script to make "envmodule"
command initialized when "pwsh" shell starts. See the PowerShell
documentation on how to customize your shell environment.

Modules installation is now operational and you can setup your
modulefiles. By default, the "modulefiles" directory in installation
directory is defined as a modulepath and contains few modulefile
examples:

   > module avail
   ------- C:/Program Files/Environment Modules/modulefiles --------
   module-git  module-info  null

Documentation of the module and ml commands and modulefile syntax can
be found in the "doc" directory in installation directory.
