Debian Codegraph @

doc/source/INSTALL-win.rst

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