====== Configuring polymake for a group of users ======

Let's suppose you want to share your polymake installation with your colleagues or to prepare it for students in your class.  First of all, you have to choose an installation location accessible from all computers in your lab (for example, an NFS or Samba share), and pass it to the [[install#configuration|build configuration]] script.  After having completed the installation by calling ''make install'', you'll surely be curious to see whether it works at all.  You'll start it, do some little exercises, and probably check for additional software you might need.  To get the first overview, use the commands ''show_credits'' and ''show_unconfigured'' .  Then, if you miss something, you'll install it - again, at some commonly accessible location - and [[:user_guide:howto:interface_config|reconfigure]] the corresponding polymake interfaces.  You might also want to add some [[:user_guide:extend:extensions]] to your installation and configure them as well.

Now everything is ready to be published - but anyone else starting to work with your installation will have to repeat all the configuration steps you've already made.  You'll have to write down detailed instructions and hand them out to each new user.  Moreover, if you decide to add some external software component or an extension later, you'll have to notify all your co-workers once again.  Isn't it tedious?

Starting with release 2.10, polymake offers a comfortable mechanism for sharing the configuration between several users.  You can specify a configuration path to polymake consisting of one or more global (read-only) configuration files and one optional private configuration location.  A global configuration file is created with a command ''export_configured'', taking a filename argument.  The file created by this command will contain all custom variables with non-default values, including those set by auto-configuration routines in the rule base.  Once you have created such a file, put its location in an environment variable
  export POLYMAKE_CONFIG_PATH="/absolute/path;user"
and propagate this setting to your users by, for example, storing it in a file in ''/etc/profile.d/'' or some other appropriate location (please consult your sysadmin if in doubt).

The configuration path may consist of several global files if needed, separated by semicolon.  The trailing element ''user'' allows the user to store his individual settings permanently in the directory ''~/.polymake''; alternative location may be specified in the environment variable ''POLYMAKE_USER_DIR'' or by putting ''user=~/other/path'' as the trailing element of the configuration path.

If the private directory is omitted in the configuration path, the user won't be able to save his private settings between the sessions (the interactive shell input history won't be stored either).  This setup might be appropriate for a teaching lab where several students share the same login account.  Another sensible use case for this mode is when polymake is called from a program linked with its [[:callable|callable library]].  Since the users of such a program doesn't see polymake directly, there might be a good reason for hindering polymake to leave any traces in the user's home directory.

The elements of the configuration path may start with ''~/'', designating the user's home directory, or refer to other environment variables using usual syntax ''$NAME''.

Finally, the configuration path may have a special form ''none'', which means the absence of any configuration at all.  This mode is primarily designed for the callable library clients.  Here polymake won't attempt to perform any automatic configuration at all, but rather run with the bare core rule set.  Please note the difference to an empty configuration path ''%%""%%'', in which case every rulefile tries to configure itself automatically, but the results are discarded at the end of the session.

===== Testing the configuration path =====

The configuration path can be changed for a single polymake session using the command line option ''%%--config-path="FILE;..."%%'' which overrides the environment variable ''POLYMAKE_CONFIG_PATH''.  The option ''%%--no-config%%'' is a shortcut for ''%%--config-path=none%%'' .

===== Effects on interactive commands =====

Few commands alter their behavior when called in a session with global configuration being in effect.

''export_configured'' produces a file which only contains the differences between the global configuration and your current settings.  To obtain the merged configuration file, containing every setting which deviates from the default regardless of its provenience, please supply the second argument '1' (or any other value equivalent to TRUE):
  export_configured("configure.pl", 1);

''reset_custom'' reverts the given custom variable to the value inherited from the global configuration, rather than to the default value as specified in the rule files.  To enforce the latter, you'll have to use ''set_custom'' with an explicit value.