Debian Codegraph @

doc/build/INSTALL-win.txt

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