Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MODULEFILE(5)		     Modules configuration		 MODULEFILE(5)

       modulefile - files containing Tcl code for the Modules package

       modulefiles  are	 written  in the Tool Command Language,	Tcl(3) and are
       interpreted by the modulecmd program via	the module(1) user  interface.
       modulefiles  can	 be loaded, unloaded, or switched on-the-fly while the
       user is working;	and can	be used	to implement site  policies  regarding
       the access and use of applications.

       A  modulefile  begins  with  the	 magic	cookie,	'#%Module'.  A version
       number may be placed after this string.	The version number  is	useful
       as  the	modulefile  format  may	 change.   If a	version	number doesn't
       exist, then modulecmd will assume the modulefile	is compatible with the
       latest  version.	 The current modulefile	version	is 1.0.	 Files without
       the magic cookie	will not be interpreted	by modulecmd.

       Each modulefile contains	the changes to a user's	environment needed  to
       access  an  application.	  Tcl  is  a simple programming	language which
       permits modulefiles to  be  arbitrarily	complex,  depending  upon  the
       application's  and  the	modulefile  writer's  needs.   If  support for
       extended	tcl (tclX) has been configured for your	 installation  of  the
       Modules	package,  you  may  use	 all the extended commands provided by
       tclX, too.

       A typical modulefile is a simple	bit of code that set or	add entries to
       the PATH, MANPATH, or other environment variables.  Tcl has conditional
       statements that are evaluated when the modulefile is loaded.   This  is
       very  effective	for  managing  path  or	 environment  changes  due  to
       different  OS  releases	or  architectures.    The   user   environment
       information  is encapsulated into a single modulefile kept in a central
       location.  The same modulefile is used by every user  on	 any  machine.
       So, from	the user's perspective,	starting an application	is exactly the
       same irrespective of the	machine	or platform they are on.

       modulefiles also	hide the notion	of different types  of	shells.	  From
       the  user's  perspective,  changing the environment for one shell looks
       exactly the same	as changing the	environment for	another	 shell.	  This
       is  useful  for	new  or	 novice	 users	and  eliminates	 the  need for
       statements such as "if you're using the C Shell do this ...,  otherwise
       if you're using the Bourne shell	do this	..."  Announcing and accessing
       new software is uniform and independent of the user's shell.  From  the
       modulefile writer's perspective,	this means one set of information will
       take care of every type of shell.

Modules	Specific Tcl Commands
       The  Modules  Package  uses  commands  which  are  extensions  to   the
       "standard"  Tool	 Command  Language  Tcl(3)  package.  Unless otherwise
       specified, the Module commands return the empty string.	Some  commands
       behave  differently  when  a  modulefile	 is  loaded  or	unloaded.  The
       command descriptions assume the modulefile is being loaded.

	      This is not a Modules-specific command, it's  actually  part  of
	      Tcl,  which has been overloaded similar to the continue and exit
	      commands to have the effect of causing  the  module  not	to  be
	      listed  as  loaded  and  not  affect  other modules being	loaded
	      concurrently.  All non-environment commands  within  the	module
	      will  be performed up to this point and processing will continue
	      on to the	next module on the command line.   The	break  command
	      will only	have this effect if not	used within a Tcl loop though.

	      An  example:  Suppose  that  a full selection of modulefiles are
	      needed for various different  architectures,  but	 some  of  the
	      modulefiles  are	not  needed  and  the  user should be alerted.
	      Having the unnecessary modulefile	be a  link  to	the  following
	      notavail modulefile will perform the task	as required.

	      ## notavail modulefile
	      proc ModulesHelp { } {
		  puts stderr	  "This	module does nothing but	alert the user"
		  puts stderr	  "that	the [module-info name] module is not available"

	      module-whatis  "Notifies user that module	is not available."
	      set curMod [module-info name]
	      if { [ module-info mode load ] } {
		  puts stderr	  "Note: '$curMod' is not available for	[uname sysname]."


       chdir directory
	      Set the current working directory	to directory.

	      This  is	not  a modules specific	command	but another overloaded
	      Tcl command and is similar to the	break or exit commands	except
	      the  module  will	 be listed as loaded as	well as	performing any
	      environment or Tcl commands up to	this point and then continuing
	      on to the	next module on the command line.  The continue command
	      will only	have this effect if not	used within a Tcl loop though.

       exit [N]
	      This is not a modules specific command  but  another  overloaded
	      Tcl  command  and	 is similar to the break or continue commands.
	      However, this command will cause the immediate cessation of this
	      module and any additional	ones on	the command line.  This	module
	      and the subsequent modules will not be  listed  as  loaded.   No
	      environment commands will	be performed in	the current module.

	      The  integer  value  N after the exit command will be used as an
	      command exit value; however, some	 shells	 (bash	being  one  of
	      them)  do	 not carry this	value through an eval though. For bash
	      and those	Bourne shells (/bin/sh)	being  emulated	 by  the  bash
	      will  have  return  a  non-zero  value as	a result of test 0 = 1
	      being appended to	the evaluate string.

       setenv variable value
	      Set environment variable to value.  The setenv command will also
	      change  the  process'  environment.  A reference using Tcl's env
	      associative array	will reference changes made  with  the	setenv
	      command.	 Changes  made	using Tcl's env	associative array will
	      NOT change the  user's  environment  variable  like  the	setenv
	      command.	 An  environment change	made this way will only	affect
	      the module parsing process.  The setenv command is  also	useful
	      for  changing  the  environment  prior  to  the  exec  or	system
	      command.	 When  a  modulefile  is  unloaded,   setenv   becomes
	      unsetenv.	  If the environment variable had been defined it will
	      be overwritten  while  loading  the  modulefile.	 A  subsequent
	      unload  will unset the environment variable - the	previous value
	      cannot be	restored!  (Unless you handle it  explicitly  ...  see

       unsetenv	variable [value]
	      Unsets  environment  variable.  However, if there	is an optional
	      value, then when unloading a module, it  will  set  variable  to
	      value.   The  unsetenv  command changes the process' environment
	      like setenv.

       append-path [ -d	C | --delim C |	--delim=C ] variable value
       prepend-path [ -d C | --delim C | --delim=C ] variable value
	      Append or	prepend	value to environment variable.	 The  variable
	      is a colon, or delimiter,	separated list such as
	      "PATH=directory:directory:directory".   The default delimiter is
	      a	colon ':', but an arbitrary one	can be given  by  the  --delim
	      option.	For  example  a	 space can be used instead (which will
	      need to be handled in the	Tcl specially by enclosing it in  "  "
	      or  {  }).   A  space,  however,	can  not  be  specified	by the
	      --delim=C	form.

	      If the variable is not set, it is	created.  When a modulefile is
	      unloaded,	append-path and	prepend-path become remove-path.

       remove-path [ -d	C | --delim C |	--delim=C ] variable value
	      Remove  value  from  the	colon, or delimiter, separated list in
	      variable.	  See  prepend-path   or   append-path	 for   further
	      explanation  of  using  an  arbitrary  delimiter.	  Every	string
	      between colons, or delimiters, in	variable is compared to	value.
	      If the two match,	value is removed from variable.

       prereq modulefile [ modulefile ...  ]
       conflict	modulefile [ modulefile	...  ]
	      prereq  and  conflict control whether or not the modulefile will
	      be loaded.  The prereq command lists modulefiles which must have
	      been  previously	loaded	before	the current modulefile will be
	      loaded.  Similarly, the conflict command lists modulefiles which
	      conflict	with  the current modulefile.  If a list contains more
	      than one modulefile, then	each member of	the  list  acts	 as  a
	      Boolean OR operation.  Multiple prereq and conflict commands may
	      be used to create	a  Boolean  AND	 operation.   If  one  of  the
	      requirements  have  not been satisfied, an error is reported and
	      the  current  modulefile	makes  no  changes   to	  the	user's

	      If an argument for prereq	is a directory and any modulefile from
	      the directory has	been loaded, then  the	prerequisite  is  met.
	      For  example,  specifying	X11 as a prereq	means that any version
	      of X11, X11/R4 or	X11/R5,	must be	loaded before proceeding.

	      If an argument  for  conflict  is	 a  directory  and  any	 other
	      modulefile  from that directory has been loaded, then a conflict
	      will occur.  For example,	specifying X11 as a conflict will stop
	      X11/R4 and X11/R5	from being loaded at the same time.

       is-loaded modulefile [ modulefile ...  ]
	      The  is-loaded command returns a true value if any of the	listed
	      modulefiles has been loaded.  If a list contains more  than  one
	      modulefile, then each member acts	as a boolean OR	operation.  If
	      an argument for is-loaded	is a directory and any modulefile from
	      the  directory  has  been	 loaded	 is-loaded would return	a true

       module [	sub-command ] [	sub-command-args ]
	      Contains the same	sub-commands as	described in the module(1) man
	      page in the Module Sub-Commands section.	This command permits a
	      modulefile to load or remove other modulefiles.  No  checks  are
	      made  to ensure that the modulefile does not try to load itself.
	      Often it is useful to have a single modulefile that  performs  a
	      number  of  module load commands.	 For example, if every user on
	      the system requires a basic set of applications loaded,  then  a
	      core   modulefile	  would	 contain  the  necessary  module  load

       module-info option [ info-args ]
	      Provide information about	the modulecmd program's	 state.	  Some
	      of  the  information  is specific	to the internals of modulecmd.
	      option is	the type of information	to be provided,	and  info-args
	      are any arguments	needed.

	      module-info type
		     Returns  either  "C"  or  "Tcl"  to indicate which	module
		     command is	being executed,	either the "C" version or  the
		     Tcl-only  version,	 to  allow  the	 modulefile  writer to
		     handle any	differences between the	two.
	      module-info flags
		     Returns the integer value of modulecmd's flags state.
	      module-info mode [modetype]
		     Returns the current modulecmd's mode as a	string	if  no
		     modetype is given.

		     Returns  1	if modulecmd's mode is modetype.  modetype can
		     be: load, remove, display,	help, whatis, switch, switch1,
		     switch2, or switch3.

	      module-info name
		     Return  the name of the modulefile.  This is not the full
		     pathname  for  modulefile.	  See  the  Modules  Variables
		     section for information on	the full pathname.

	      module-info specified
		     Return  the  name	of  the	 modulefile  specified	on the
		     command line.

	      module-info shell
		     Return  the  current  shell  under	 which	modulecmd  was
		     invoked.  This is the first parameter of modulecmd, which
		     is	normally hidden	by the module alias.

	      module-info shelltype
		     Return the	family of the shell under which	modulefile was
		     invoked.	As  of	module-info  shell this	depends	on the
		     first parameter of	modulecmd. The output reflects a shell
		     type   determining	 the  shell  syntax  of	 the  commands
		     produced by modulecmd.

	      module-info alias	name
		     Returns the full module file name	to  which  the	module
		     file alias	name is	assigned

	      module-info version module-file
		     Returns  a	 list of all symbolic versions assigned	to the
		     passed  module-file.  The	paremeter  module-file	 might
		     either  be	 a  full  qualified  module file with name and
		     version, another symbolic module file name	 or  a	module
		     file alias.

       module-version module-file version-name [version-name ...]
	      Assigns the symbolic version-name	to the module file module-file
	      This command should be placed in one of the modulecmd  rc	 files
	      in  order	 to  provide  shorthand	invocations of frequently used
	      module file names.

	      The special version-name default specifies the  default  version
	      to be used for module commands, if no specific version is	given.
	      This replaces the	definitions  made  in  the  .version  file  in
	      former modulecmd releases.

	      The parameter module-file	may be either

		     a fully qualified modulefile with name and	version
		     a symbolic	module file name
		     another module file alias

       module-alias name module-file
	      Assignes	the  module  file  module-file to the alias name. This
	      command should be	placed in one of the  modulecmd	 rc  files  in
	      order to provide shorthand invocations of	frequently used	module
	      file names.

	      The parameter module-file	may be either

		     a fully qualified modulefile with name and	version
		     a symbolic	module file name
		     another module file alias

       module-trace {on|off}  [command	[command  ...]]	  [-module  modulefile
       [modulefile ...]]
	      Switches tracing on or off. Without parameters this command will
	      affect  globally	all  tracing  setups  for  all	commands   and
	      modulefiles. The command parameter may be	used to	affect tracing
	      of specified module commands only	and the	switch -module finally
	      limits  the affect of the	module-trace command to	a well defined
	      set of module files.

	      The command may be one of	the following

		     avail - 'module avail' command
		     clear - 'module clear' command
		     display - 'module display'	command
		     init - 'module init' command
		     help - 'module help' command
		     list - 'module list' command
		     load - 'module load' command
		     purge - 'module purge' command
		     switch - 'module switch' command
		     unuse - 'module unuse' command
		     unload - 'module unload' command
		     update - 'module update' command
		     use - 'module use'	command

	      The module parameter specifies a set of module files  using  TCL
	      regular expressions. For example

		     .*	 will affect all module	files
		     */2.0 affects all module files at version 2.0
		     gnu/.*  affects all versions of the gnu modulefile
		     gnu/2.0 affects only version 2.0 of the gnu modulefile

	      The module parameter is prepended	to the current tracing pattern
	      list for the specified module command.  It is evaluated from the
	      left  to	the  right.  The  first	 matching  pattern defines the
	      tracing parameter.

	      The internal trace pattern list is stored	as a  colon  separated
	      list.   In  advanced user	level only, colons may be specified on
	      the module parameter of  the  module-trace  command.  This  will
	      directly	take  effect  in  the  internal	trace pattern list. In
	      novice or	expert user level a warning messge will	be generated.

       module-user level
	      Defines the user level under wich	module-cmd  runs.  This	 takes
	      effect  on the error messages being produced and on the behavior
	      of modulecmd in case of detecting	an outage.

	      The level	parameter specifies the	user level and may be  one  of
	      the following values:

		     advanced, adv - advanced user level
		     expert, exp - expert user level
		     novice, nov - novice user level

       module-verbosity	{on|off}
	      Switches verbose modulecmd message display on or off.

       module-log error-weight log-facility
	      Defines whether error messages of	the specified weight should be
	      logged and conditionally assignes	a log-facility.

	      The error-weight parameter  specifies  the  error	 level	to  be
	      logged.  It may be one of	the following values:

		     verb - verbose messages
		     info - informal messages
		     debug - debugging messages
		     trace - tracing output
		     warn - warnings
		     prob - problems (normally the modulecmd may be completed)
		     error  - errors (which normally leads to unsuccessful end
		     of	the modulecmd)
		     fatal - fatal system errors
		     panic - very fatal	system errors, e.g.  internal  program

	      The  log-facility	 parameter specifies the log destination. This
	      may either switch	off logging for	 the  specified	 error-weight,
	      direct  log  messages to a special stream	or a file or specify a
	      syslog facility for logging. The following values	are allowed:

		     stderr, stdout - predefined output	streams	for normal and
		     error  outputs.  Note,  that  stdout is normally used for
		     passing parameters	to the invoking	shell. Directing error
		     output  to	 this  stream  might  screw  up	 the modulecmd
		     integration to your shell.
		     a syslog facility - directs logging to  the  syslog.  See
		     syslog.conf(5)  for  detailed  description	 of  the valid
		     syslog facilities.
		     null, none	-  will	 suppress  logging  of	the  specified
		     a	filename  - is recognized by the first character being
		     either a '.' or a '/'. You	must have write	permission  to
		     the file you specify.

       module-whatis string
	      Defines a	string which is	displayed in case of the invocation of
	      the 'module whatis' command.  There may be more than one module-
	      whatis  line  in	a modulefile. This command takes no actions in
	      case of load, display, etc. invocations of modulecmd.

	      The string parameter has to  be  enclosed	 in  double-quotes  if
	      there's  more  than  one word specified. Words are defined to be
	      separated	by whitespace characters (space, tab, cr).

       set-alias alias-name alias-string
	      Sets an alias or function	with the name alias-name in the	user's
	      environment  to  the  string  alias-string.   Arguments  can  be
	      specified	using the Bourne Shell style  of  function  arguments.
	      If  the  string  contains	 "$1", then this will become the first
	      argument when the	alias is interpreted by	the shell.  The	string
	      "$*"  corresponds	 to  all  of the arguments given to the	alias.
	      The character '$'	may be escaped using the '\' character.

	      For some shells, aliases are not possible	and the	command	has no
	      effect.	For Bourne shell derivatives, a	shell function will be
	      written (if supported) to	give the impression of an alias.  When
	      a	modulefile is unloaded,	set-alias becomes unset-alias.

       unset-alias alias-name
	      Unsets   an  alias  with	the  name  alias-name  in  the	user's
	      environment.  If the shell supports functions then the shell  is
	      instructed to unset function alias-name.

       system string
	      Pass  string  to	the  C	library	 routine  system(3).   For the
	      system(3)	call modulecmd redirects stdout	to stderr since	stdout
	      would be parsed by the evaluating	shell.	The exit status	of the
	      executed command is returned.

       uname field
	      Provide fast  lookup  of	system	information  on	 systems  that
	      support  uname(3).   uname  is  significantly  faster than using
	      system to	execute	a program  to  return  host  information.   If
	      uname(3)	is  not	available, gethostname(3) or some program will
	      make the nodename	 available.   uname  will  return  the	string
	      "unknown"	if information is unavailable for the field.

	      uname  will invoke getdomainname in order	to figure out the name
	      of the domain.

	      field values are:

		     sysname - the operating system name
		     nodename -	the hostname
		     domain - the name of the domain
		     release - the operating system release
		     version - the operating system version
		     machine - a standard name that  identifies	 the  system's

       x-resource resource-string
       x-resource filename
	      Merge  resources	into the X11 resource database.	 The resources
	      are used to control look and behavior of X11 applications.   The
	      command  will  attempt  to read resources	from filename.	If the
	      argument	isn't  a  valid	 file  name,  then  string   will   be
	      interpreted  as  a  resource.   If  a  file is found, it will be
	      filtered through the cpp(1) preprocessor,	just as	xrdb(1)	 would

	      modulefiles  that	use this command, should in most cases contain
	      one or more x-resource lines, each defining  one	X11  resource.
	      Reading  resources  from	filename  is  much  slower, due	to the
	      preprocessing.   The  DISPLAY  environment  variable  should  be
	      properly	set  and  the  X11 server should be accessible.	 If x-
	      resource	can't  manipulate  the	X11  resource  database,   the
	      modulefile will exit with	an error message.


	      x-resource /u2/staff/leif/.xres/Ileaf
		     The  file	Ileaf is preprocessed by cpp(1)	and the	result
		     is	merged into the	X11 resource database.

	      x-resource [glob ~/.xres/ileaf]
		     The Tcl glob function is used to have the modulefile read
		     different resource	files for different users.

	      x-resource {Ileaf.popup.saveUnder: True}
		     Merge the Ileaf resource into the X11 resource database.

Modules	Variables
       The ModulesCurrentModulefile variable contains the full pathname	of the
       modulefile being	interpreted.

Locating Modulefiles
       Every directory in MODULEPATH is	searched to find  the  modulefile.   A
       directory   in	MODULEPATH  can	 have  an  arbitrary  number  of  sub-
       directories.  If	the user names a modulefile  to	 be  loaded  which  is
       actually	 a  directory, the directory is	opened and a search begins for
       an actual modulefile.  First, modulecmd looks for a file	with the  name
       .modulerc  in  the directory. If	this file exists, its contents will be
       evaluated as if it was a	module	file  to  be  loaded.  You  may	 place
       module-version	 and   module-alias   commands	 inside	  this	 file.
       Additionally,  before  seeking  for  .modulerc  files  in  the	module
       directory,  the	global	.modulerc  file	 is  sourced,  too. If a named
       version default now exists for  the  module  file  to  be  loaded,  the
       assigned	modulefile now will be sourced.	Otherwise the file .version is
       looked up in the	directory.  If the .version file exists, it is	opened
       and  interpreted	as Tcl code and	takes precedence over a	.modulerc file
       in the same directory.  If the Tcl variable ModulesVersion  is  set  by
       the  .version  file,  modulecmd	will use the name as if	it specifies a
       modulefile in the directory. This will become the default  module  file
       in this case.  If ModulesVersion	is a directory,	the search begins anew
       down that directory. If the name	does not match any  files  located  in
       the  current  directory,	 the  search  continues	 through the remaining
       directories in MODULEPATH.

       Every .version  and .modulerc  file  found  is  Tcl  interpreted.   So,
       changes	made  in  these	 file will affect the subsequently interpreted

       If  no  default	version	 may  be  figured  out,	  then	 the   highest
       lexicographically  sorted  modulefile under the directory using the 'C'
       locale will be used.

       For example, it is possible for a user to have a	 directory  named  X11
       which  simply  contains a .version file specifying which	version	of X11
       is to be	loaded.	 Such a	file would look	like:

	      ##  The desired version of X11
	      set ModulesVersion "R4"

Modulefile Specific Help
       Users  can  request  help  about	 a  specific  modulefile  through  the
       module(1)  command.   The  modulefile  can print	helpful	information or
       start help oriented programs by defining	a ModulesHelp subroutine.  The
       subroutine  will	be called when the 'module help	modulefile' command is

Modulefile Display
       The 'module display modulefile' command will detail  all	 changes  that
       will  be	 made  to  the	environment.   After  displaying  all  of  the
       environment changes modulecmd will call the ModulesDisplay  subroutine.
       The  ModulesDisplay  subroutine	is  a  good  place  to	put additional
       descriptive information about the modulefile.

	      Path of directories containing modulefiles.


       module(1),  Tcl(3),  TclX(3),  xrdb(1),	cpp(1),	 system(3),  uname(3),
       gethostname(3) getdomainname(3)

       Tcl was developed by John Ousterhout at the University of California at

       TclX was	developed by Karl Lehenbauer and Mark Diekhans.

Modules	version	3.2.10		   July	2009			 MODULEFILE(5)

NAME | DESCRIPTION | Modules Specific Tcl Commands | Modules Variables | Locating Modulefiles | Modulefile Specific Help | Modulefile Display | ENVIRONMENT | VERSION | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:

home | help