Collaboration diagram for Command Line Program Management (commandline):

Description

Provides functionality for managing command line programs.

This module provides utility classes and functions for implementing command line programs. They are mainly used within GROMACS, but can also be used from external programs if they want to get a similar user experience to GROMACS tools.

The classes exposed from this module can be roughly divided into two groups:

Helper classes/functions for implementing the main() function. See Using GROMACS as a library for an overview of those available for user programs. These are declared in cmdlineinit.h (gmx::ICommandLineModule is declared in cmdlinemodule.h and gmx::ICommandLineOptions in cmdlineoptionsmodule.h).

Additionally, for internal GROMACS use, gmx::CommandLineModuleManager provides the functionality to implement the gmx wrapper binary, as well as command line options common to all GROMACS programs (such as -version). This is described in more detail at Wrapper binary implementation.
Helper classes for particular command line tasks:
- gmx::CommandLineParser implements command line parsing to assign values to gmx::Options (see Extensible Handling of Options (options)).
- gmx::CommandLineHelpWriter writes help text for a program that uses the parser.
- parse_common_args() is an old interface to GROMACS command line parsing. This is still used by many parts of GROMACS.

Author: Teemu Murtola teemu.nosp@m..mur.nosp@m.tola@.nosp@m.gmai.nosp@m.l.com

Namespaces
	gmx
	Generic GROMACS namespace.

Classes
class	gmx::CommandLineHelpContext::Impl
	Private implementation class for CommandLineHelpContext. More...

class	gmx::CommandLineHelpContext
	Context information for writing out command-line help. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::RootHelpTopic
	Help topic that forms the root of the help tree for the help subcommand. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::IHelpExport
	Callbacks for exporting help information for command-line modules. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::CommandsHelpTopic
	Help topic for listing the commands. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::ModuleHelpTopic
	Help topic wrapper for a command-line module. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::HelpExportReStructuredText
	Implements export for web pages as reStructuredText. More...

class	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::HelpExportCompletion
	Implements export for command-line completion. More...

class	gmx::CommandLineHelpModule
	Command-line module for producing help. More...

class	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::IOptionsFormatter
	Interface for output format specific formatting of options. More...

class	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsFilter
	Output format independent processing of options. More...

class	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::SynopsisFormatter
	Formatter implementation for synopsis. More...

class	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsListFormatter
	Formatter implementation for help export. More...

class	gmx::CommandLineHelpWriter
	Writes help information for Options. More...

class	gmx::CommandLineModuleSettings
	Settings to pass information between a module and the general runner. More...

class	gmx::ICommandLineModule
	Module that can be run from command line using CommandLineModuleManager. More...

class	gmx::anonymous_namespace{cmdlinemodulemanager.cpp}::CMainCommandLineModule
	Implements a ICommandLineModule, given a function with C/C++ main() signature. More...

class	gmx::CommandLineModuleManager
	Implements a wrapper command-line interface for multiple modules. More...

class	gmx::CommandLineModuleGroup
	Handle to add content to a group added with CommandLineModuleManager::addModuleGroup(). More...

class	gmx::CommandLineModuleGroupData
	Internal data for a CommandLineModuleManager module group. More...

class	gmx::CommandLineCommonOptionsHolder
	Encapsulates some handling of common options to the wrapper binary. More...

class	gmx::ICommandLineOptionsModuleSettings
	Settings to pass information between a CommandLineOptionsModule and generic code that runs it. More...

class	gmx::ICommandLineOptionsModule
	Module that can be run from a command line and uses gmx::Options for argument processing. More...

class	gmx::CommandLineParser
	Implements command-line parsing for Options objects. More...

class	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::DefaultExecutableEnvironment
	Default implementation for IExecutableEnvironment. More...

class	gmx::IExecutableEnvironment
	Allows customization of the way various directories are found by CommandLineProgramContext. More...

class	gmx::CommandLineProgramContext
	Program context implementation for command line programs. More...

struct	t_filenm
	File name option definition for C code. More...

class	gmx::anonymous_namespace{pargs.cpp}::OptionsAdapter
	Conversion helper between t_pargs/t_filenm and Options. More...

struct	t_pargs
	Command-line argument definition for C code. More...

class	gmx::test::MockModule
	Mock implementation of gmx::ICommandLineModule. More...

class	gmx::test::MockOptionsModule
	Mock implementation of gmx::ICommandLineOptionsModule. More...

class	gmx::test::CommandLineModuleManagerTestBase
	Test fixture for tests using gmx::CommandLineModuleManager. More...

Macros
#define	ffSET 1 << 0
	Whether a file name option is set.

#define	ffREAD 1 << 1
	Whether a file name option specifies an input file.

#define	ffWRITE 1 << 2
	Whether a file name option specifies an output file.

#define	ffOPT 1 << 3
	Whether a file name option specifies an optional file.

#define	ffLIB 1 << 4
	Whether a file name option specifies a library file.

#define	ffMULT 1 << 5
	Whether a file name option accepts multiple file names.

#define	ffALLOW_MISSING 1 << 6
	Whether an input file name option accepts non-existent files.

#define	ffRW (ffREAD \| ffWRITE)
	Convenience flag for an input/output file.

#define	ffOPTRD (ffREAD \| ffOPT)
	Convenience flag for an optional input file.

#define	ffOPTWR (ffWRITE \| ffOPT)
	Convenience flag for an optional output file.

#define	ffOPTRW (ffRW \| ffOPT)
	Convenience flag for an optional input/output file.

#define	ffLIBRD (ffREAD \| ffLIB)
	Convenience flag for a library input file.

#define	ffLIBOPTRD (ffOPTRD \| ffLIB)
	Convenience flag for an optional library input file.

#define	ffRDMULT (ffREAD \| ffMULT)
	Convenience flag for an input file that accepts multiple files.

#define	ffOPTRDMULT (ffRDMULT \| ffOPT)
	Convenience flag for an optional input file that accepts multiple files.

#define	ffWRMULT (ffWRITE \| ffMULT)
	Convenience flag for an output file that accepts multiple files.

#define	ffOPTWRMULT (ffWRMULT \| ffOPT)
	Convenience flag for an optional output file that accepts multiple files.

#define	opt2FILE(opt, nfile, fnm, mode) gmx_ffopen(opt2fn(opt, nfile, fnm), mode)
	Returns a file pointer from the filename.

#define	ftp2FILE(ftp, nfile, fnm, mode) gmx_ffopen(ftp2fn(ftp, nfile, fnm), mode)
	Returns a file pointer from the file type.

#define	PCA_CAN_VIEW (1 << 5)
	Add option -w to view output files (must be implemented in program). More...

#define	PCA_CAN_BEGIN (1 << 6)
	Add option to set begin time for trajectory reading. More...

#define	PCA_CAN_END (1 << 7)
	Add option to set end time for trajectory reading. More...

#define	PCA_CAN_DT (1 << 14)
	Add option to set time step for trajectory reading. More...

#define	PCA_CAN_TIME (PCA_CAN_BEGIN \| PCA_CAN_END \| PCA_CAN_DT)
	Add all options for trajectory time control. More...

#define	PCA_TIME_UNIT (1 << 15)
	Add option -tu to set time unit for output. More...

#define	PCA_CAN_SET_DEFFNM (1 << 10)
	Add option -deffnm to set default for all file options. More...

#define	PCA_NOEXIT_ON_ARGS (1 << 11)
	Do not raise a fatal error when invalid options are encountered. More...

#define	PCA_DISABLE_INPUT_FILE_CHECKING (1 << 17)
	Don't do any special processing for ffREAD files.

Typedefs
typedef std::unique_ptr < ICommandLineModule >	gmx::CommandLineModulePointer
	Smart pointer type for managing a ICommandLineModule.

typedef std::map< std::string, CommandLineModulePointer >	gmx::CommandLineModuleMap
	Container type for mapping module names to module objects.

typedef std::unique_ptr < CommandLineModuleGroupData >	gmx::CommandLineModuleGroupDataPointer
	Smart pointer type for managing a CommandLineModuleGroup.

typedef std::vector < CommandLineModuleGroupDataPointer >	gmx::CommandLineModuleGroupList
	Container type for keeping a list of module groups.

typedef std::unique_ptr < IExecutableEnvironment >	gmx::ExecutableEnvironmentPointer
	Shorthand for a smart pointer to IExecutableEnvironment.

Enumerations
enum	{ etINT, etINT64, etREAL, etTIME, etSTR, etBOOL, etRVEC, etENUM, etNR }
	Command line argument type. More...

enum	gmx::ShellCompletionFormat { gmx::eShellCompletionFormat_Bash }
	Output format for ShellCompletionWriter. More...

Functions
void	gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::initProgramLinks (HelpLinks *links, const CommandLineHelpModuleImpl &helpModule)
	Adds hyperlinks to modules within this binary. More...

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::formatOptionNameAndValue (const OptionInfo &option, std::string name, std::string value)
	Formats option name and value.

std::string	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::defaultOptionValue (const OptionInfo &option)
	Formats the default option value as a string.

std::string	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::fileOptionFlagsAsString (const FileNameOptionInfo &option, bool bAbbrev)
	Formats the flags for a file option as a string.

std::string	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::descriptionWithOptionDetails (const CommonFormatterData &common, const OptionInfo &option)
	Formats the description for an option as a string.

void	gmx::anonymous_namespace{cmdlineinit.cpp}::broadcastWorld (int size, void *buffer)
	Broadcasts given data from rank zero to all other ranks.

void	gmx::anonymous_namespace{cmdlineinit.cpp}::broadcastArguments (int argc, char **argv)
	Broadcasts command-line arguments to all ranks. More...

CommandLineProgramContext &	gmx::initForCommandLine (int argc, char **argv)
	Initializes the GROMACS library for command-line use. More...

void	gmx::finalizeForCommandLine ()
	Deinitializes the GROMACS library after initForCommandLine(). More...

void	gmx::writeCommandLineHelpCMain (const CommandLineHelpContext &context, const char name, int(mainFunction)(int argc, char *argv[]))
	Helper to implement ICommandLineModule::writeHelp() with a C-like main() function that calls parse_common_args(). More...

std::string	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::quoteIfNecessary (const char *str)
	Quotes a string if it contains spaces.

std::filesystem::path	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findFullBinaryPath (const std::filesystem::path &invokedName, const IExecutableEnvironment &env)
	Finds the absolute path of the binary from `argv`[0]. More...

bool	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::isAcceptableLibraryPath (const std::filesystem::path &path)
	Returns whether given path contains files from `share/top/`. More...

bool	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::isAcceptableLibraryPathPrefix (const std::filesystem::path &path)
	Returns whether given path prefix contains files from `share/top/`. More...

std::filesystem::path	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findFallbackInstallationPrefixPath ()
	Returns a fallback installation prefix path. More...

std::filesystem::path	gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findInstallationPrefixPath (const std::filesystem::path &binaryPath, bool *bSourceLayout)
	Generic function to find data files based on path of the binary. More...

virtual std::filesystem::path	gmx::IExecutableEnvironment::getWorkingDirectory () const =0
	Returns the working directory when the program was launched.

virtual std::vector < std::filesystem::path >	gmx::IExecutableEnvironment::getExecutablePaths () const =0
	Returns list of paths where executables are searched for. More...

	gmx::CommandLineProgramContext::CommandLineProgramContext ()
	Constructs an empty context object. More...

	gmx::CommandLineProgramContext::CommandLineProgramContext (const char *binaryName)
	Initializes a program context object with binary name only. More...

	gmx::CommandLineProgramContext::CommandLineProgramContext (int argc, const char *const argv[])
	Initializes a program context object based on command line. More...

	gmx::CommandLineProgramContext::CommandLineProgramContext (int argc, const char *const argv[], ExecutableEnvironmentPointer env)
	Initializes a program context object based on command line. More...

void	gmx::CommandLineProgramContext::setDisplayName (const std::string &name)
	Sets a display name for the binary. More...

const char *	gmx::CommandLineProgramContext::programName () const override
	Returns the name of the binary as it was invoked without any path. More...

const char *	gmx::CommandLineProgramContext::displayName () const override
	Returns a display name of the current module. More...

std::filesystem::path	gmx::CommandLineProgramContext::fullBinaryPath () const override
	Returns the full path of the running binary. More...

InstallationPrefixInfo	gmx::CommandLineProgramContext::installationPrefix () const override
	Returns the installation prefix (for finding GROMACS data files). More...

const char *	gmx::CommandLineProgramContext::commandLine () const override
	Returns the full command line used to invoke the binary. More...

const char *	opt2fn (const char *opt, int nfile, const t_filenm fnm[])
	Returns the filename belonging to cmd-line option opt, or NULL when no such option.

gmx::ArrayRef< const std::string >	opt2fns (const char *opt, int nfile, const t_filenm fnm[])
	Returns the filenames belonging to cmd-line option opt. More...

gmx::ArrayRef< const std::string >	opt2fnsIfOptionSet (const char *opt, int nfile, const t_filenm fnm[])
	Returns the filenames belonging to cmd-line option opt when set, returns an empty vector when the option is not set. More...

const char *	ftp2fn (int ftp, int nfile, const t_filenm fnm[])
	Returns the first file name with type ftp, or NULL when none found.

gmx::ArrayRef< const std::string >	ftp2fns (int ftp, int nfile, const t_filenm fnm[])
	Returns the filenames for the first option with type ftp. More...

bool	ftp2bSet (int ftp, int nfile, const t_filenm fnm[])
	Returns TRUE when this file type has been found on the cmd-line.

bool	opt2bSet (const char *opt, int nfile, const t_filenm fnm[])
	Returns TRUE when this option has been found on the cmd-line.

const char *	opt2fn_null (const char *opt, int nfile, const t_filenm fnm[])
	Returns the file name belonging top cmd-line option opt, or NULL when no such option. More...

const char *	ftp2fn_null (int ftp, int nfile, const t_filenm fnm[])
	Returns the first file name with type ftp, or NULL when none found. More...

bool	is_optional (const t_filenm *fnm)
	Returns whether or not this filenm is optional.

bool	is_output (const t_filenm *fnm)
	Returns whether or not this filenm is output.

bool	is_set (const t_filenm *fnm)
	Returns whether or not this filenm is set.

bool	hasSuffixFromNoAppend (std::string_view filename)
	Return whether `filename` might have been produced by mdrun -noappend. More...

int	add_suffix_to_output_names (t_filenm fnm, int nfile, const char suffix)
	When we do checkpointing, this routine is called to check for previous output files and append a '.partNNNN' suffix before the (output) file extensions. If there was already a '.partNNNN' suffix before the file extension, that is removed before the new suffix is added.

XvgFormat	gmx::anonymous_namespace{pargs.cpp}::getDefaultXvgFormat ()
	Returns the default xvg format, as modified by GMX_VIEW_XVG if that environment variable is set.

int	nenum (const char *const enumc[])
	Returns ordinal number for an etENUM argument. More...

int	opt2parg_int (const char *option, int nparg, t_pargs pa[])
	Returns value of an etINT option. More...

bool	opt2parg_bool (const char *option, int nparg, t_pargs pa[])
	Returns value of an etBOOL option. More...

real	opt2parg_real (const char *option, int nparg, t_pargs pa[])
	Returns value of an etREAL/etTIME option. More...

const char *	opt2parg_str (const char *option, int nparg, t_pargs pa[])
	Returns value of an etSTR option. More...

const char *	opt2parg_enum (const char *option, int nparg, t_pargs pa[])
	Returns value of an etENUM option. More...

bool	opt2parg_bSet (const char option, int nparg, const t_pargs pa)
	Returns whether an argument has been set. More...

bool	parse_common_args (int argc, char argv[], unsigned long Flags, int nfile, t_filenm fnm[], int npargs, t_pargs pa, int ndesc, const char desc, int nbugs, const char bugs, gmx_output_env_t *oenv)
	Parse command-line arguments. More...

void	anonymous_namespace{cmdlinehelpmodule.cpp}::initOptionsBasic (gmx::IOptionsContainer options, gmx::ICommandLineOptionsModuleSettings settings)
	Initializes Options for help export tests.

void	gmx::test::anonymous_namespace{cmdlinemodulemanagertest.cpp}::disableNice (gmx::CommandLineModuleSettings *settings)
	Helper method to disable nice() calls from CommandLineModuleManager.

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsFilter::formatSelected (FilterType type, IOptionsFormatter *formatter, const Options &options)
	Formats selected options using the formatter.

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsFilter::visitSection (const OptionSectionInfo &section) override
	Called for each section.

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsFilter::visitOption (const OptionInfo &option) override
	Called for each option.

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::SynopsisFormatter::start (const char *name)
	Starts formatting the synopsis.

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::SynopsisFormatter::finish ()
	Finishes formatting the synopsis.

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::SynopsisFormatter::formatOption (const OptionInfo &option) override
	Formats a single option option.

	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsListFormatter::OptionsListFormatter (const HelpWriterContext &context, const CommonFormatterData &common, const char *title)
	Creates a helper object for formatting options.

void	gmx::anonymous_namespace{cmdlinehelpwriter.cpp}::OptionsListFormatter::formatOption (const OptionInfo &option) override
	Formats a single option option.

Variables
const CommandLineHelpContext *	gmx::anonymous_namespace{cmdlinehelpcontext.cpp}::g_globalContext = nullptr
	Stores the global context set with GlobalCommandLineHelpContext. More...

std::unique_ptr < CommandLineProgramContext >	gmx::anonymous_namespace{cmdlineinit.cpp}::g_commandLineContext
	Global context instance initialized in initForCommandLine().

std::unique_ptr< DataFileFinder >	gmx::anonymous_namespace{cmdlineinit.cpp}::g_libFileFinder
	Global library data file finder that respects GMXLIB.

Directories
directory	commandline
	Command Line Program Management (commandline)

directory	tests
	Unit tests for Command Line Program Management (commandline).

Files
file	cmdlinehelpcontext.cpp
	Implements gmx::CommandLineHelpContext.

file	cmdlinehelpcontext.h
	Declares gmx::CommandLineHelpContext.

file	cmdlinehelpmodule.cpp
	Implements gmx::CommandLineHelpModule.

file	cmdlinehelpmodule.h
	Declares gmx::CommandLineHelpModule.

file	cmdlinehelpwriter.cpp
	Implements gmx::CommandLineHelpWriter.

file	cmdlinehelpwriter.h
	Declares gmx::CommandLineHelpWriter.

file	cmdlineinit.cpp
	Implements functions from cmdlineinit.h.

file	cmdlineinit.h
	Declares functions for initializing the GROMACS library for command line use.

file	cmdlinemodule.cpp
	Implements classes from cmdlinemodule.h.

file	cmdlinemodule.h
	Declares gmx::ICommandLineModule and supporting classes.

file	cmdlinemodulemanager.cpp
	Implements gmx::CommandLineModuleManager.

file	cmdlinemodulemanager.h
	Declares gmx::CommandLineModuleManager.

file	cmdlinemodulemanager_impl.h
	Declares implementation types for gmx::CommandLineModuleManager.

file	cmdlineoptionsmodule.cpp
	Implements supporting routines for gmx::ICommandLineOptionsModule.

file	cmdlineoptionsmodule.h
	Declares gmx::ICommandLineOptionsModule and supporting routines.

file	cmdlineparser.cpp
	Implements gmx::CommandLineParser.

file	cmdlineparser.h
	Declares gmx::CommandLineParser.

file	cmdlineprogramcontext.cpp
	Implements gmx::CommandLineProgramContext.

file	cmdlineprogramcontext.h
	Declares gmx::CommandLineProgramContext.

file	filenm.h
	Declares t_filenm for old-style command-line parsing of file name options.

file	pargs.h
	Declares `t_pargs`, parse_common_args() and related methods.

file	shellcompletions.cpp
	Implements gmx::ShellCompletionWriter.

file	shellcompletions.h
	Declares gmx::ShellCompletionWriter.

file	cmdlinehelpmodule.cpp
	Tests gmx::CommandLineHelpModule through gmx::CommandLineModuleManager.

file	cmdlinehelpwriter.cpp
	Tests gmx::CommandLineHelpWriter.

file	cmdlinemodulemanager.cpp
	Tests gmx::CommandLineModuleManager.

file	cmdlinemodulemanagertest.cpp
	Implements classes from cmdlinemodulemanagertest.h.

file	cmdlinemodulemanagertest.h
	Test fixture and helper classes for tests using gmx::CommandLineModuleManager.

file	cmdlineparser.cpp
	Tests gmx::CommandLineParser.

file	cmdlineprogramcontext.cpp
	Tests for gmx::CommandLineProgramContext.

file	filenm.cpp
	Tests filename-handling functionality.

file	pargs.cpp
	Tests parse_common_args().

file	viewit.h
	Provides function to open output files automatically (with some X11 programs).

Macro Definition Documentation

#define PCA_CAN_BEGIN (1 << 6)

Add option to set begin time for trajectory reading.

#define PCA_CAN_DT (1 << 14)

Add option to set time step for trajectory reading.

#define PCA_CAN_END (1 << 7)

Add option to set end time for trajectory reading.

#define PCA_CAN_SET_DEFFNM (1 << 10)

Add option -deffnm to set default for all file options.

#define PCA_CAN_TIME (PCA_CAN_BEGIN | PCA_CAN_END | PCA_CAN_DT)

Add all options for trajectory time control.

#define PCA_CAN_VIEW (1 << 5)

Add option -w to view output files (must be implemented in program).

#define PCA_NOEXIT_ON_ARGS (1 << 11)

Do not raise a fatal error when invalid options are encountered.

#define PCA_TIME_UNIT (1 << 15)

Add option -tu to set time unit for output.

Enumeration Type Documentation

anonymous enum

Command line argument type.

enum gmx::ShellCompletionFormat

Output format for ShellCompletionWriter.

Enumerator
eShellCompletionFormat_Bash	Shell completions for bash.

Function Documentation

void gmx::anonymous_namespace{cmdlineinit.cpp}::broadcastArguments	(	int *	argc,
		char ***	argv
	)

Broadcasts command-line arguments to all ranks.

MPI does not ensure that command-line arguments would be passed on any other rank than zero, but our code wants to parse them on each rank separately.

const char * gmx::CommandLineProgramContext::commandLine ( ) const

overridevirtual

Returns the full command line used to invoke the binary.

Does not throw.

Implements gmx::IProgramContext.

gmx::CommandLineProgramContext::CommandLineProgramContext ( )

Constructs an empty context object.

All methods in the constructed object return dummy values.

gmx::CommandLineProgramContext::CommandLineProgramContext ( const char * binaryName )

explicit

Initializes a program context object with binary name only.

Parameters

[in] binaryName Name of the binary.

This is needed for unit testing purposes. The constructed object works as if the command line consisted of only of the binary name.

gmx::CommandLineProgramContext::CommandLineProgramContext	(	int	argc,
		const char *const	argv[]
	)

Initializes a program context object based on command line.

Parameters

[in]	argc	argc value passed to main().
[in]	argv	argv array passed to main().

gmx::CommandLineProgramContext::CommandLineProgramContext	(	int	argc,
		const char *const	argv[],
		ExecutableEnvironmentPointer	env
	)

Initializes a program context object based on command line.

Parameters

[in]	argc	argc value passed to main().
[in]	argv	argv array passed to main().
[in]	env	Customizes the way the binary name is handled.

This overload allows one to customize the way the binary is located by providing a custom IExecutableEnvironment implementation. This is mainly useful for testing purposes to make it possible to test different paths without setting environment variables, changing the working directory or doing other process-wide operations. It may also be useful for making Gromacs behave better when linked into a non-Gromacs executable (with possible extensions in IExecutableEnvironment).

const char * gmx::CommandLineProgramContext::displayName ( ) const

overridevirtual

Returns a display name of the current module.

The returned value equals programName(), unless a separate display name has been set with setDisplayName().

Does not throw.

Implements gmx::IProgramContext.

void gmx::finalizeForCommandLine ( )

Deinitializes the GROMACS library after initForCommandLine().

Calls gmx::finalize() and additionally undoes the work done by initForCommandLine().

See Also: gmx::finalize()

std::filesystem::path gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findFallbackInstallationPrefixPath ( )

Returns a fallback installation prefix path.

Checks a few standard locations for the data files before returning a configure-time hard-coded path. The hard-coded path is preferred if it actually contains the data files, though.

std::filesystem::path gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findFullBinaryPath	(	const std::filesystem::path &	invokedName,
		const IExecutableEnvironment &	env
	)

Finds the absolute path of the binary from argv[0].

Parameters

[in]	invokedName	`argv`[0] the binary was invoked with.
[in]	env	Executable environment.

Returns: The full path of the binary.

If a binary with the given name cannot be located, invokedName is returned.

std::filesystem::path gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findInstallationPrefixPath	(	const std::filesystem::path &	binaryPath,
		bool *	bSourceLayout
	)

Generic function to find data files based on path of the binary.

Parameters

[in]	binaryPath	Absolute path to the binary.
[out]	bSourceLayout	Set to `true` if the binary is run from the build tree and the original source directory can be found.

Returns: Path to the share/top/ data files.

The search based on the path only works if the binary is in the same relative path as the installed GROMACS binaries. If the binary is somewhere else, a hard-coded fallback is used. This doesn't work if the binaries are somewhere else than the path given during configure time...

Extra logic is present to allow running binaries from the build tree such that they use up-to-date data files from the source tree.

const char* ftp2fn_null	(	int	ftp,
		int	nfile,
		const t_filenm	fnm[]
	)

Returns the first file name with type ftp, or NULL when none found.

Also return NULL when ftp is optional and option is not set.

gmx::ArrayRef<const std::string> ftp2fns	(	int	ftp,
		int	nfile,
		const t_filenm	fnm[]
	)

Returns the filenames for the first option with type ftp.

An assertion will fail when when none found.

std::filesystem::path gmx::CommandLineProgramContext::fullBinaryPath ( ) const

overridevirtual

Returns the full path of the running binary.

Exceptions

std::bad_alloc if out of memory.

Returns argv[0] if there was an error in finding the absolute path.

Implements gmx::IProgramContext.

virtual std::vector<std::filesystem::path> gmx::IExecutableEnvironment::getExecutablePaths ( ) const

pure virtual

Returns list of paths where executables are searched for.

The returned list should be in priority order. An empty string in the returned list corresponds to getWorkindDirectory().

Implemented in gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::DefaultExecutableEnvironment.

bool hasSuffixFromNoAppend ( std::string_view filename )

Return whether filename might have been produced by mdrun -noappend.

If so, it must match "prefix.partNNNN.extension", for four decimal digits N and non-empty prefix and extension.

CommandLineProgramContext & gmx::initForCommandLine	(	int *	argc,
		char ***	argv
	)

Initializes the GROMACS library for command-line use.

Parameters

[in]	argc	argc value passed to main().
[in]	argv	argv array passed to main().

Returns: Reference to initialized program context object.

This function is tailored for use in command line applications. For other usage, combination of gmx::init() and gmx::setProgramContext() provides more flexible initialization alternatives. Unlike gmx::init(), calls to this method cannot be nested.

The command line arguments are communicated so that they can be parsed on each processor. argc and argv are passed to gmx::init(); see there for additional discussion. This method does not place any additional limitations, but generally there should be no need to pass NULL values.

Does not throw. Terminates the program on out-of-memory error.

This method is not thread-safe, since it is intended to be the first method called. See setProgramContext() for additional discussion.

See Also: gmx::init(); setProgramContext()

void gmx::anonymous_namespace{cmdlinehelpmodule.cpp}::initProgramLinks	(	HelpLinks *	links,
		const CommandLineHelpModuleImpl &	helpModule
	)

Adds hyperlinks to modules within this binary.

Parameters

[in,out]	links	Links are added here.
[in]	helpModule	Help module to get module information from.

Exceptions

std::bad_alloc if out of memory.

Initializes a HelpLinks object with links to modules defined in helpModule.

InstallationPrefixInfo gmx::CommandLineProgramContext::installationPrefix ( ) const

overridevirtual

Returns the installation prefix (for finding GROMACS data files).

Exceptions

std::bad_alloc if out of memory.

Returns a hardcoded path set during configuration time if there is an error in finding the library data files.

Implements gmx::IProgramContext.

bool gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::isAcceptableLibraryPath ( const std::filesystem::path & path )

Returns whether given path contains files from share/top/.

Only checks for a single file that has an uncommon enough name.

bool gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::isAcceptableLibraryPathPrefix ( const std::filesystem::path & path )

Returns whether given path prefix contains files from share/top/.

Parameters

[in] path Path prefix to check.

Returns: true if path contains the data files.

Checks whether path could be the installation prefix where share/top/ files have been installed: appends the relative installation path of the data files and calls isAcceptableLibraryPath().

int nenum ( const char *const enumc[] )

Returns ordinal number for an etENUM argument.

Parameters

[in] enumc Array passed to t_pargs for an etENUM argument.

Returns: Index of selected enum value in the array.

See t_pargs::u::c for the expected format of the array, including how the first element should be initialized. Note that the return value starts at one instead of zero: if the first enum value is selected, this returns 1.

const char* opt2fn_null	(	const char *	opt,
		int	nfile,
		const t_filenm	fnm[]
	)

Returns the file name belonging top cmd-line option opt, or NULL when no such option.

Also return NULL when opt is optional and option is not set.

gmx::ArrayRef<const std::string> opt2fns	(	const char *	opt,
		int	nfile,
		const t_filenm	fnm[]
	)

Returns the filenames belonging to cmd-line option opt.

An assertion will fail when the option does not exist.

gmx::ArrayRef<const std::string> opt2fnsIfOptionSet	(	const char *	opt,
		int	nfile,
		const t_filenm	fnm[]
	)

Returns the filenames belonging to cmd-line option opt when set, returns an empty vector when the option is not set.

An assertion will fail when the option does not exist.

bool opt2parg_bool	(	const char *	option,
		int	nparg,
		t_pargs	pa[]
	)

Returns value of an etBOOL option.

Parameters

[in]	option	Name of etBOOL argument to query.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: Value of option.

option must specify a valid argument in pa of the correct type.

bool opt2parg_bSet	(	const char *	option,
		int	nparg,
		const t_pargs *	pa
	)

Returns whether an argument has been set.

Parameters

[in]	option	Name of argument to check.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: true if option has been set.

option must specify a valid argument in pa.

const char* opt2parg_enum	(	const char *	option,
		int	nparg,
		t_pargs	pa[]
	)

Returns value of an etENUM option.

Parameters

[in]	option	Name of etENUM argument to query.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: Value of option.

option must specify a valid argument in pa of the correct type.

int opt2parg_int	(	const char *	option,
		int	nparg,
		t_pargs	pa[]
	)

Returns value of an etINT option.

Parameters

[in]	option	Name of etINT argument to query.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: Value of option.

option must specify a valid argument in pa of the correct type.

real opt2parg_real	(	const char *	option,
		int	nparg,
		t_pargs	pa[]
	)

Returns value of an etREAL/etTIME option.

Parameters

[in]	option	Name of etREAL/etTIME argument to query.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: Value of option.

option must specify a valid argument in pa of the correct type.

const char* opt2parg_str	(	const char *	option,
		int	nparg,
		t_pargs	pa[]
	)

Returns value of an etSTR option.

Parameters

[in]	option	Name of etSTR argument to query.
[in]	nparg	Number of elements in `pa`.
[in]	pa	Array of arguments.

Returns: Value of option.

option must specify a valid argument in pa of the correct type.

bool parse_common_args	(	int *	argc,
		char *	argv[],
		unsigned long	Flags,
		int	nfile,
		t_filenm	fnm[],
		int	npargs,
		t_pargs *	pa,
		int	ndesc,
		const char **	desc,
		int	nbugs,
		const char **	bugs,
		gmx_output_env_t **	oenv
	)

Parse command-line arguments.

Some common default arguments are also recognized in addition to those provided through pa. The set of recognized default arguments is affected by Flags.

Recognized arguments are removed from the list.

For full functionality, this function needs to be used within a function that is passed to gmx_run_cmain(). It should be called as the first thing in that function. Initialization code can be executed before it, but you need to be aware that if the program is executed with -h and MPI, the code before parse_common_args() only executes on the main node.

If the return value is FALSE, the program should return immediately (this is necessary for -h and a few other cases).

See Also: gmx_run_cmain().

const char * gmx::CommandLineProgramContext::programName ( ) const

overridevirtual

Returns the name of the binary as it was invoked without any path.

Does not throw.

Implements gmx::IProgramContext.

void gmx::CommandLineProgramContext::setDisplayName ( const std::string & name )

Sets a display name for the binary.

Exceptions

std::bad_alloc if out of memory.

This is used with the wrapper binary to add the name of the invoked module to the name of the binary shown.

It is not threadsafe if there are concurrent calls to displayName() before this method has returned. Thread safety is not required for the normal initialization sequence of command line programs; it is called in the wrapper binary before the control passes to the actual module which may create threads.

void gmx::writeCommandLineHelpCMain	(	const CommandLineHelpContext &	context,
		const char *	name,
		int()(int argc, char argv[])	mainFunction
	)

Helper to implement ICommandLineModule::writeHelp() with a C-like main() function that calls parse_common_args().

Parameters

[in]	context	Context object for writing the help.
[in]	name	Name of the module.
[in]	mainFunction	C-like main() function that calls parse_common_args().

Variable Documentation

const CommandLineHelpContext* gmx::anonymous_namespace{cmdlinehelpcontext.cpp}::g_globalContext = nullptr

Stores the global context set with GlobalCommandLineHelpContext.

This is not protected by a mutex, since it is only used in command-line start-up (i.e., single-threaded context), and is inherently not thread-safe.

Description

Namespaces

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Directories

Files

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation

Variable Documentation