Gromacs  2022.2
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Namespaces | Classes | Macros | Typedefs | Enumerations | Functions | Variables | Directories | Files
Command Line Program Management (commandline)
+ 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:

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}::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::string gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findFullBinaryPath (const std::string &invokedName, const IExecutableEnvironment &env)
 Finds the absolute path of the binary from argv[0]. More...
 
bool gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::isAcceptableLibraryPath (const std::string &path)
 Returns whether given path contains files from share/top/. More...
 
bool gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::isAcceptableLibraryPathPrefix (const std::string &path)
 Returns whether given path prefix contains files from share/top/. More...
 
std::string gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findFallbackInstallationPrefixPath ()
 Returns a fallback installation prefix path. More...
 
std::string gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findInstallationPrefixPath (const std::string &binaryPath, bool *bSourceLayout)
 Generic function to find data files based on path of the binary. More...
 
virtual std::string gmx::IExecutableEnvironment::getWorkingDirectory () const =0
 Returns the working directory when the program was launched.
 
virtual std::vector< std::string > 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...
 
const char * 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).
 
file  commandline.h
 Public API convenience header for managing command line 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.

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]binaryNameName 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]argcargc value passed to main().
[in]argvargv 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]argcargc value passed to main().
[in]argvargv array passed to main().
[in]envCustomizes 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::string 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::string gmx::anonymous_namespace{cmdlineprogramcontext.cpp}::findFullBinaryPath ( const std::string &  invokedName,
const IExecutableEnvironment &  env 
)

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

Parameters
[in]invokedNameargv[0] the binary was invoked with.
[in]envExecutable environment.
Returns
The full path of the binary.

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

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

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

Parameters
[in]binaryPathAbsolute path to the binary.
[out]bSourceLayoutSet 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.

const char * gmx::CommandLineProgramContext::fullBinaryPath ( ) const
overridevirtual

Returns the full path of the running binary.

Exceptions
std::bad_allocif out of memory.

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

Implements gmx::IProgramContext.

virtual std::vector<std::string> 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]argcargc value passed to main().
[in]argvargv 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]linksLinks are added here.
[in]helpModuleHelp module to get module information from.
Exceptions
std::bad_allocif 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_allocif 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::string &  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::string &  path)

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

Parameters
[in]pathPath 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]enumcArray 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]optionName of etBOOL argument to query.
[in]npargNumber of elements in pa.
[in]paArray 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]optionName of argument to check.
[in]npargNumber of elements in pa.
[in]paArray 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]optionName of etENUM argument to query.
[in]npargNumber of elements in pa.
[in]paArray 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]optionName of etINT argument to query.
[in]npargNumber of elements in pa.
[in]paArray 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]optionName of etREAL/etTIME argument to query.
[in]npargNumber of elements in pa.
[in]paArray 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]optionName of etSTR argument to query.
[in]npargNumber of elements in pa.
[in]paArray 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 master 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_allocif 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]contextContext object for writing the help.
[in]nameName of the module.
[in]mainFunctionC-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.