modules/doc/source/diff_with_c-version.pod

=head1 Slight differences with C-version

This document lists the differences of the functionalities that can be found between the C-version of the Modules package ahd the Tcl-version. The goal of this document is to reference the features of the C-version that are missing or behave differently on the Tcl-version and the features that are specific to the Tcl version. These information help to clearly know what functionalities are available on C-version that will change in case of migration to the Tcl-version.

First part the of the document covers the features that are missing or that behave differently on Tcl-version than on C-version. The second part of the document covers the features that are specific to the Tcl-version thus missing on C-version. Comparison takes as a basis version C<3.2.10> of Modules C against version C<1.729> of Modules-Tcl. Any change made past these versions will explicitely mention the release number starting from the difference between the two Modules flavors appears or disappears.

For missing features, this document only lists their name or the command line argument related to them. Please refer to the B<module>(1) and the B<modulefile>(4) man pages of the C or Tcl version to learn the details about these features.

=head1 Features missing or with different behavior than C-version

This section describes the features of the C-version that are not supported or that behave differently on the Tcl-version.

=head2 Package Initialization

Tcl-version does not support I<ruby> as code output.

Until C<vX.XXX>: Tcl-version did not support I<cmake> as code output.

B<MODULESBEGINENV> environment snapshot functionality is not supported on Tcl-version.

=head2 Command line switches

Until C<vX.XXX>: command line switches relative to a sub-command must be specified on the command line after the sub-command. For instance C<module --terse list> will raise an error on Tcl-version, C<module list --terse> should be used instead. Starting C<vX.XXX>, Tcl-version handles position constraint of switches in the same way than C-version does.

=over

=item B<--force>, B<-f>

=item B<--human>

=item B<--verbose>, B<-v>

=item B<--silent>, B<-s>

=item B<--create>, B<-c>

=item B<--icase>, B<-i>

=item B<--userlvl> lvl, B<-u> lvl

These command line switches are not supported on Tcl-version.

Until C<vX.XXX>: these command line switches were producing an I<Invalid option> error. Starting C<vX.XXX>, Tcl-version produces an I<Unsupported option> warning and command is ran with the unsupported switches ignored.

=item B<-h>

This command line switch is short version of B<--help> switch on Tcl-version whereas it is short version of B<--human> switch on C-version.

=back

=head2 Module Sub-Commands

On C-version, paths composing the B<MODULEPATH> environment variable may contain reference to environment variable. These variable references are resolved dynamically when B<MODULEPATH> is looked at during module sub-command action like B<avail>.

=over

=item B<clear>

=item B<update>

These module sub-commands are not supported on Tcl-version.

=item B<refresh>

On C-version, only the shell aliases defined by the currently loaded modulefiles are set again on a B<refresh> command. Whereas on Tcl-version this command is an alias on the B<reload> command that B<unload> then B<load> all the currently loaded modulefiles.

=item B<help>

C-version redirects output made on stdout in B<ModulesHelp> Tcl procedure to stderr.

During an B<help> sub-command, only the B<ModulesHelp> Tcl procedure of a modulefile is interpreted on C-version. Tcl-version interprets all the content of the modulefile, then call the B<ModulesHelp> procedure if it exists.

Since C<v1.923>: on Tcl-version B<ModulesHelp> subroutine is not ran if an error occurred during the interpretation of the I<modulefile> main body.

=item B<display>

Since C<v1.923>: on Tcl-version B<ModulesDisplay> subroutine is not ran if an error occurred during the interpretation of the I<modulefile> main body.

=item B<avail>

On C-version, the same Tcl interpreter is used for the interpretation of all F<.modulerc> or F<.version> files during an B<avail> command but the state of this interpreter is not reset between each interpretation. So some variable and procedure definitions may spread from one interpretation to another.

=item B<apropos>

On Tcl-version, I<string> passed as argument is always searched in a case insensitive manner.

=item B<load>

On Tcl-version the value of an environment variable is set even if the new value is the same as the current value of this variable in environment.

=item B<switch>

When switching on Tcl-version an I<old> modulefile by a I<new> one, no error is raised if I<old> modulefile is not currently loaded.

When switching on Tcl-version an I<old> modulefile by a I<new> one, this I<new> modulefile does not keep the position that the I<old> modulefile had in the B<LOADEDMODULES> list as done on C-version but it is appended to the end of the list. Same goes for PATH-like environment variables: replaced PATH component is appended to the end or prepended to the beginning of the relative PATH-like variable, not appended or prepended relatively to the position hold by the swapped PATH component.

=item B<initadd>

=item B<initprepend>

=item B<initswitch>

On Tcl-version no message is displayed to give details on how list of modulefiles to load has been altered in initialization file.

=item B<initrm>

No message is displayed on Tcl-version to inform of the modulefiles that have been removed from the loading list in initialization file.

Until C<vX.XXX>: when last modulefile from a loading list is asked to be removed, the entire B<module load> line is removed from initialization file. Since C<vX.XXX>, empty B<module load> line is left on Tcl-version when last modulefile from a line is asked to be removed. On C-version B<module load null> line is set in this case.

=item B<initclear>

Until C<vX.XXX>: all B<module load> lines are removed from shell initialization files on Tcl-version when B<initclear> is invoked. Since C<vX.XXX>, empty B<module load> lines are left on Tcl-version whereas B<module load null> lines are set on C-version.

=back

=head2 Modules Specific Tcl Commands

=over

=item B<exit>

On Tcl-version code passed to the B<exit> Modules specific Tcl command will not be thrown to be the B<module> return value.

=item B<module-alias>

=item B<module-version>

Since C<v1.923>: in case the specified aliased module or the symbolic version introduces a resolution loop with already defined aliases or symbolic versions, this new alias or symbolic version is not registered and an error message is raised. On C-version and on previous Tcl-version releases, alias or symbolic version introducing loop are registered as the modulefile resolution is not computed at registration time.

=item B<module-info>

=over

=item B<module-info flags>

=item B<module-info trace>

=item B<module-info tracepat>

=item B<module-info user>

These B<module-info> options are related to C-version specific features so they are available on Tcl-version but with a dummy implementation that always returns false or an empty value.

=item B<module-info mode>

During an B<unload> sub-command, I<unload> is returned instead of I<remove>. However if B<mode> is tested against I<remove> value, true will be returned.

During a B<switch> sub-command, I<unload> then I<load> is returned instead of I<switch1> then I<switch2> then I<switch3>. However if B<mode> is tested against I<switch> value, true will be returned.

=item B<module-info version>

Since C<v1.923>: declared aliases or symbolic versions are not registered anymore if they introduce a resolution loop. As a result B<module-info version> does not return an I<*undef*> string value as it does not face resolution loop situation anymore.

=item B<module-info symbols>

Since C<v1.923>: declared aliases or symbolic versions are not registered anymore if they introduce a resolution loop. As a consequence symbolic versions introducing loop situation are not part anymore of the B<module-info symbols> returned result as they are not registered.

=back

=item B<module-log>

=item B<module-trace>

=item B<module-user>

=item B<module-verbosity>

These Modules specific Tcl commands are related to C-version specific features so they are available on Tcl-version but with a dummy implementation that always displays a warning message saying the command is not implemented.

=item B<module-whatis>

When multiple words are passed as argument to B<module-whatis> but they are not enclosed in double-quotes or curly braces they will be displayed as a single line on Tcl-version whereas C-version displays them as one line per word.

=item B<set-alias>

Whereas C-version sets a shell function when variables are in use in alias value on Bourne shell derivatives, Tcl-version always defines a shell alias never a shell function.

=back

=head2 Locating Modulefiles

On Tcl-version when a module alias is set and overrides name of an existing directory, this alias is taken into account to locate the default version of this module name and the I<modulefiles> locating in the directory are ignored.

Since C<v1.832>: when looking for an implicit default in a I<modulefile> directory, aliases are taken into account in addition to I<modulefiles> and directories to determine the highest numerically sorted element.

Since C<v1.832>: distinguish access issue (permission denied) from find issue (cannot locate) when trying to access directly a directory or a modulefile as done on B<load>, B<display> or B<whatis> commands. In addition, on this kind of access not readable F<.modulerc> or F<.version> files are ignored rather producing a missing magic cookie error.

=head1 Features specific to the Tcl-version

This section describes the features of the Tcl-version that are not supported on the C-version. Please refer to the above section for features supported by both versions but behaving differently.

=head2 Package Initialization

C-version does not support I<fish>, I<lisp> and I<tcl> as code output.

=head2 Command line switches

=over

=item B<--debug>, B<-D>

=item B<--default>, B<-d>

=item B<--latest>, B<-L>

These command line switches are not supported on C-version.

=back

=head2 Module Sub-Commands

=over

=item B<reload>

=item B<source>

=item B<search>

=item B<save>

=item B<restore>

=item B<saverm>

=item B<saveshow>

=item B<savelist>

=item B<path>

=item B<paths>

=item B<autoinit>

=item B<aliases>

These module sub-commands are not supported on C-version.

=item B<test>

This command appeared on C<v1.923> and is not supported on C-version.

=item B<avail>

=item B<whatis>

=item B<apropos>

Non-critical errors are not displayed on these sub-commands. Only valid results are returned.

Module aliases are included in the result of these sub-commands. They are displayed in the module path section where they are defined or in a I<global/user modulerc> section for aliases set in user's or global modulerc file. A B<@> symbol is added in parenthesis next to their name to distinguish them from I<modulefiles>.

Since C<v1.832>: search may be performed with an alias or a symbolic version-name passed as argument.

=back

=head2 Collections

Modules collections are not supported on C-version.

=head2 Modules Specific Tcl Commands

=over

=item B<module>

Since C<v1.832>: in case of B<module load> command specifying multiple I<modulefiles>, when mode is set to B<unload> these I<modulefiles> will be unloaded in the reverse order to ensure correct handling of prerequisites.

=item B<module-info>

=over

=item B<module-info command>

This B<module-info> option is not supported on C-version.

=back

=back