| 1 |
.. _INSTALL-win: |
| 2 |
|
| 3 |
Installing Modules on Windows |
| 4 |
============================= |
| 5 |
|
| 6 |
This document is an overview of building and installing Modules on a Windows |
| 7 |
platform. |
| 8 |
|
| 9 |
|
| 10 |
Requirements |
| 11 |
------------ |
| 12 |
|
| 13 |
Modules consists of one Tcl script so to run it from a user shell the only |
| 14 |
requirement is to have a working version of ``tclsh`` (version 8.5 or later) |
| 15 |
available on your system. ``tclsh`` is a part of `Tcl`_. |
| 16 |
|
| 17 |
.. _Tcl: http://www.tcl-lang.org/software/tcltk/ |
| 18 |
|
| 19 |
A specific distribution zipball is provided to install Modules on a Windows |
| 20 |
platform. Content of this distribution zipball is ready for use and does not |
| 21 |
require a specific build step. All scripts and documentation found in this |
| 22 |
zipball are pre-built so there is no specific tools are required to install |
| 23 |
Modules from the Windows-specific distribution zipball. |
| 24 |
|
| 25 |
|
| 26 |
Installation instructions |
| 27 |
------------------------- |
| 28 |
|
| 29 |
1. Install a Tcl binary distribution for Windows like `ActiveTcl`_ or |
| 30 |
`Magicsplat Tcl/Tk for Windows`_. Follow instructions provided with the |
| 31 |
chosen distribution to install it. |
| 32 |
|
| 33 |
.. _ActiveTcl: https://www.activestate.com/tcl/ |
| 34 |
.. _Magicsplat Tcl/Tk for Windows: https://www.magicsplat.com/tcl-installer/ |
| 35 |
|
| 36 |
2. Once installed, verify that the ``tclsh`` command is correctly found in |
| 37 |
defined ``PATH`` by typing the following command from a Windows ``cmd`` |
| 38 |
shell (``windows`` string should be obtained as result):: |
| 39 |
|
| 40 |
> echo puts $tcl_platform(platform) | tclsh |
| 41 |
windows |
| 42 |
|
| 43 |
3. Download Modules specific distribution zipball for Windows from |
| 44 |
`SourceForge`_ or `GitHub`_. Such distribution archives are available |
| 45 |
for Modules release starting version ``4.5.0`` and can be distinguished |
| 46 |
from the source tarball by the ``-win`` suffix in their name. |
| 47 |
|
| 48 |
.. _SourceForge: https://sourceforge.net/projects/modules/files/Modules/ |
| 49 |
.. _GitHub: https://github.com/envmodules/modules/releases |
| 50 |
|
| 51 |
4. Unpack downloaded zip file then enter deflated directory and execute the |
| 52 |
``INSTALL.bat`` script file found in it. This script installs files by |
| 53 |
default in ``C:\Program Files\Environment Modules\`` directory and adds the |
| 54 |
``bin`` directory in this installation location to the system-wide ``PATH`` |
| 55 |
environment variable. |
| 56 |
|
| 57 |
If you use Powershell Core on Windows, please use the ``INSTALL_PWSH.bat`` |
| 58 |
instead. It won't add the ``bin`` directory to the system-wide ``PATH`` |
| 59 |
environment variable because the ``module`` command will interfere with |
| 60 |
Powershell's ``module`` keyword. |
| 61 |
|
| 62 |
.. note:: ``INSTALL.bat`` and ``INSTALL_PWSH.bat`` scripts may require to be |
| 63 |
run with administrator rights to perform installation correctly. |
| 64 |
|
| 65 |
5. Once installed, verify that the ``module`` command is correctly found. If |
| 66 |
you used the ``INSTALL.bat`` script, the commands should be in the defined |
| 67 |
``PATH``. Verify by typing the following command from a Windows ``cmd`` |
| 68 |
shell:: |
| 69 |
|
| 70 |
> module -V |
| 71 |
Modules Release 5.5.0 (2024-11-11) |
| 72 |
|
| 73 |
If your used the ``INSTALL_PWSH.bat`` script, the environment has to be |
| 74 |
initialized first. Verify by typing the following commands from a Windows |
| 75 |
``cmd`` shell:: |
| 76 |
|
| 77 |
> call "C:\Program Files\Environment Modules\init\cmd.cmd" |
| 78 |
> module -V |
| 79 |
Modules Release 5.5.0 (2024-11-11) |
| 80 |
|
| 81 |
And the following commands from a Windows ``pwsh`` shell:: |
| 82 |
|
| 83 |
> . "C:\Program Files\Environment Modules\init\pwsh.ps1" |
| 84 |
> envmodule --version |
| 85 |
Modules Release 5.5.0 (2024-11-11) |
| 86 |
|
| 87 |
Installation location can be adapted by running the ``INSTALL.bat`` and |
| 88 |
``INSTALL_PWSH.bat`` scripts from a ``cmd`` console shell and passing desired |
| 89 |
installation target as argument. For instance to install Modules in |
| 90 |
``C:\EnvironmentModules`` directory:: |
| 91 |
|
| 92 |
> INSTALL.bat C:\EnvironmentModules |
| 93 |
|
| 94 |
|
| 95 |
For PowerShell, you may adapt profile script to make ``envmodule`` command |
| 96 |
initialized when ``pwsh`` shell starts. See the PowerShell documentation on |
| 97 |
how to `customize your shell environment <https://learn.microsoft.com/en-us/powershell/scripting/learn/shell/creating-profiles>`_. |
| 98 |
|
| 99 |
Alternatively, if you use `Windows Terminal`_, a PowerShell or ``pwsh`` |
| 100 |
profile can be set to initialize Modules on startup without altering the |
| 101 |
system-wide ``PATH`` environment variable and without running an install |
| 102 |
script. Once the Windows-specific distribution zipball has been unpacked to |
| 103 |
a directory of your choice (for instance ``C:\Program Files\Environment |
| 104 |
Modules``), open the Windows Terminal settings, select the profile to |
| 105 |
adapt and set its *Command line* to:: |
| 106 |
|
| 107 |
pwsh.exe -NoExit -Command "& Import-Module 'C:\Program Files\Environment Modules\init\pwsh.ps1'" |
| 108 |
|
| 109 |
Use ``powershell.exe`` instead of ``pwsh.exe`` to rely on the Windows |
| 110 |
built-in PowerShell rather than PowerShell Core, and adapt the path passed |
| 111 |
to ``Import-Module`` to match where the distribution zipball was unpacked. |
| 112 |
The ``envmodule`` command then gets initialized every time this profile |
| 113 |
starts. |
| 114 |
|
| 115 |
.. _Windows Terminal: https://learn.microsoft.com/en-us/windows/terminal/ |
| 116 |
|
| 117 |
Modules installation is now operational and you can setup your modulefiles. By |
| 118 |
default, the ``modulefiles`` directory in installation directory is defined as |
| 119 |
a modulepath and contains few modulefile examples:: |
| 120 |
|
| 121 |
> module avail |
| 122 |
------- C:/Program Files/Environment Modules/modulefiles -------- |
| 123 |
module-git module-info null |
| 124 |
|
| 125 |
Documentation of the :ref:`module(1)`, :ref:`ml(1)` and :ref:`envml(1)` |
| 126 |
commands and :ref:`modulefile(5)` syntax can be found in the ``doc`` directory |
| 127 |
in installation directory. |
| 128 |
|
| 129 |
.. warning:: If both Modules and the *MSVC x86 toolchain* are installed and |
| 130 |
Modules has been initialized in the current shell session, the command |
| 131 |
``ml`` will refer to the Modules version rather than the *MSVC assembler*. |
| 132 |
To invoke the *MSVC assembler* while Modules is active, you must call it |
| 133 |
explicitly as ``ml.exe``. |