diff --git a/Source/cmCTest.h b/Source/cmCTest.h index 5c34a94c4..b6657c95f 100644 --- a/Source/cmCTest.h +++ b/Source/cmCTest.h @@ -53,6 +53,13 @@ class cmXMLWriter; #endif #define cout no_cout_use_cmCTestLog +/** \class cmCTest + * \brief Represents a ctest invocation. + * + * This class represents a ctest invocation. It is the top level class when + * running ctest. + * + */ class cmCTest { friend class cmCTestRunTest; @@ -119,7 +126,7 @@ public: typedef std::vector VectorOfStrings; typedef std::set SetOfStrings; - ///! Process Command line arguments + /** Process Command line arguments */ int Run(std::vector&, std::string* output = CM_NULLPTR); /** @@ -135,22 +142,24 @@ public: * * The execution of the steps (or #Part) should look like this: * + * /code * ctest foo; * foo.Initialize(); * // Set some things on foo * foo.ProcessSteps(); * foo.Finalize(); + * /endcode * * \sa Initialize(), Finalize(), Part, PartInfo, SetTest() */ int ProcessSteps(); - /* + /** * A utility function that returns the nightly time */ struct tm* GetNightlyTime(std::string const& str, bool tomorrowtag); - /* + /** * Is the tomorrow tag set? */ bool GetTomorrowTag() { return this->TomorrowTag; } @@ -160,14 +169,14 @@ public: */ int TestDirectory(bool memcheck); - ///! what is the configuraiton type, e.g. Debug, Release etc. + /** what is the configuraiton type, e.g. Debug, Release etc. */ std::string const& GetConfigType(); double GetTimeOut() { return this->TimeOut; } void SetTimeOut(double t) { this->TimeOut = t; } double GetGlobalTimeout() { return this->GlobalTimeout; } - // how many test to run at the same time + /** how many test to run at the same time */ int GetParallelLevel() { return this->ParallelLevel; } void SetParallelLevel(int); @@ -205,19 +214,19 @@ public: cmCTest(); ~cmCTest(); - //! Set the notes files to be created. + /** Set the notes files to be created. */ void SetNotesFiles(const char* notes); void PopulateCustomVector(cmMakefile* mf, const std::string& definition, std::vector& vec); void PopulateCustomInteger(cmMakefile* mf, const std::string& def, int& val); - ///! Get the current time as string + /** Get the current time as string */ std::string CurrentTime(); - //! tar/gzip and then base 64 encode a file + /** tar/gzip and then base 64 encode a file */ std::string Base64GzipEncodeFile(std::string const& file); - //! base64 encode a file + /** base64 encode a file */ std::string Base64EncodeFile(std::string const& file); /** @@ -227,11 +236,13 @@ public: */ double GetRemainingTimeAllowed(); - ///! Open file in the output directory and set the stream + /** + * Open file in the output directory and set the stream + */ bool OpenOutputFile(const std::string& path, const std::string& name, cmGeneratedFileStream& stream, bool compress = false); - ///! Should we only show what we would do? + /** Should we only show what we would do? */ bool GetShowOnly(); bool ShouldUseHTTP10() { return this->UseHTTP10; } @@ -247,11 +258,11 @@ public: std::string GetStopTime() { return this->StopTime; } void SetStopTime(std::string const& time); - // Used for parallel ctest job scheduling + /** Used for parallel ctest job scheduling */ std::string GetScheduleType() { return this->ScheduleType; } void SetScheduleType(std::string type) { this->ScheduleType = type; } - ///! The max output width + /** The max output width */ int GetMaxTestNameWidth() const; void SetMaxTestNameWidth(int w) { this->MaxTestNameWidth = w; } @@ -279,31 +290,37 @@ public: std::string* stdErr, int* retVal = CM_NULLPTR, const char* dir = CM_NULLPTR, double timeout = 0.0); - //! Clean/make safe for xml the given value such that it may be used as - // one of the key fields by CDash when computing the buildid. + /** + * Clean/make safe for xml the given value such that it may be used as + * one of the key fields by CDash when computing the buildid. + */ static std::string SafeBuildIdField(const std::string& value); - //! Start CTest XML output file + /** Start CTest XML output file */ void StartXML(cmXMLWriter& xml, bool append); - //! End CTest XML output file + /** End CTest XML output file */ void EndXML(cmXMLWriter& xml); - //! Run command specialized for make and configure. Returns process status - // and retVal is return value or exception. + /** + * Run command specialized for make and configure. Returns process status + * and retVal is return value or exception. + */ int RunMakeCommand(const char* command, std::string& output, int* retVal, const char* dir, int timeout, std::ostream& ofs); - /* - * return the current tag - */ + /** Return the current tag */ std::string GetCurrentTag(); - //! Get the path to the build tree + /** Get the path to the build tree */ std::string GetBinaryDir(); - //! Get the short path to the file. This means if the file is in binary or - // source directory, it will become /.../relative/path/to/file + /** + * Get the short path to the file. + * + * This means if the file is in binary or + * source directory, it will become /.../relative/path/to/file + */ std::string GetShortPathToFile(const char* fname); enum @@ -313,7 +330,7 @@ public: CONTINUOUS }; - // provide some more detailed info on the return code for ctest + /** provide some more detailed info on the return code for ctest */ enum { UPDATE_ERRORS = 0x01, @@ -325,14 +342,16 @@ public: SUBMIT_ERRORS = 0x40 }; - ///! Are we producing XML + /** Are we producing XML */ bool GetProduceXML(); void SetProduceXML(bool v); - //! Run command specialized for tests. Returns process status and retVal is - // return value or exception. If environment is non-null, it is used to set - // environment variables prior to running the test. After running the test, - // environment variables are restored to their previous values. + /** + * Run command specialized for tests. Returns process status and retVal is + * return value or exception. If environment is non-null, it is used to set + * environment variables prior to running the test. After running the test, + * environment variables are restored to their previous values. + */ int RunTest(std::vector args, std::string* output, int* retVal, std::ostream* logfile, double testTimeOut, std::vector* environment); @@ -343,13 +362,13 @@ public: */ int ExecuteHandler(const char* handler); - /* + /** * Get the handler object */ cmCTestGenericHandler* GetHandler(const char* handler); cmCTestGenericHandler* GetInitializedHandler(const char* handler); - /* + /** * Set the CTest variable from CMake variable */ bool SetCTestConfigurationFromCMakeVariable(cmMakefile* mf, @@ -357,37 +376,42 @@ public: const std::string& cmake_var, bool suppress = false); - //! Make string safe to be send as an URL + /** Make string safe to be send as an URL */ static std::string MakeURLSafe(const std::string&); /** Decode a URL to the original string. */ static std::string DecodeURL(const std::string&); - //! Should ctect configuration be updated. When using new style ctest - // script, this should be true. + /** + * Should ctect configuration be updated. When using new style ctest + * script, this should be true. + */ void SetSuppressUpdatingCTestConfiguration(bool val) { this->SuppressUpdatingCTestConfiguration = val; } - //! Add overwrite to ctest configuration. - // The format is key=value + /** + * Add overwrite to ctest configuration. + * + * The format is key=value + */ void AddCTestConfigurationOverwrite(const std::string& encstr); - //! Create XML file that contains all the notes specified + /** Create XML file that contains all the notes specified */ int GenerateNotesFile(const VectorOfStrings& files); - //! Submit extra files to the server + /** Submit extra files to the server */ bool SubmitExtraFiles(const char* files); bool SubmitExtraFiles(const VectorOfStrings& files); - //! Set the output log file name + /** Set the output log file name */ void SetOutputLogFileName(const char* name); - //! Set the visual studio or Xcode config type + /** Set the visual studio or Xcode config type */ void SetConfigType(const char* ct); - //! Various log types + /** Various log types */ enum { DEBUG = 0, @@ -400,15 +424,15 @@ public: OTHER }; - //! Add log to the output + /** Add log to the output */ void Log(int logType, const char* file, int line, const char* msg, bool suppress = false); - //! Get the version of dart server + /** Get the version of dart server */ int GetDartVersion() { return this->DartVersion; } int GetDropSiteCDash() { return this->DropSiteCDash; } - //! Add file to be submitted + /** Add file to be submitted */ void AddSubmitFile(Part part, const char* name); std::vector const& GetSubmitFiles(Part part) { @@ -416,7 +440,9 @@ public: } void ClearSubmitFiles(Part part) { this->Parts[part].SubmitFiles.clear(); } - //! Read the custom configuration files and apply them to the current ctest + /** + * Read the custom configuration files and apply them to the current ctest + */ int ReadCustomConfigurationFileTree(const char* dir, cmMakefile* mf); std::vector& GetInitialCommandLineArguments() @@ -424,7 +450,7 @@ public: return this->InitialCommandLineArguments; } - //! Set the track to submit to + /** Set the track to submit to */ void SetSpecificTrack(const char* track); const char* GetSpecificTrack(); @@ -452,10 +478,13 @@ public: { return this->Definitions; } - // return the number of times a test should be run + + /** Return the number of times a test should be run */ int GetTestRepeat() { return this->RepeatTests; } - // return true if test should run until fail + + /** Return true if test should run until fail */ bool GetRepeatUntilFail() { return this->RepeatUntilFail; } + private: int RepeatTests; bool RepeatUntilFail; @@ -490,7 +519,7 @@ private: bool ShowOnly; - //! Map of configuration properties + /** Map of configuration properties */ typedef std::map CTestConfigurationMap; std::string CTestConfigFile; @@ -554,41 +583,41 @@ private: */ int Initialize(const char* binary_dir, cmCTestStartCommand* command); - //! parse the option after -D and convert it into the appropriate steps + /** parse the option after -D and convert it into the appropriate steps */ bool AddTestsForDashboardType(std::string& targ); - //! read as "emit an error message for an unknown -D value" + /** read as "emit an error message for an unknown -D value" */ void ErrorMessageUnknownDashDValue(std::string& val); - //! add a variable definition from a command line -D value + /** add a variable definition from a command line -D value */ bool AddVariableDefinition(const std::string& arg); - //! parse and process most common command line arguments + /** parse and process most common command line arguments */ bool HandleCommandLineArguments(size_t& i, std::vector& args, std::string& errormsg); - //! hande the -S -SP and -SR arguments + /** hande the -S -SP and -SR arguments */ void HandleScriptArguments(size_t& i, std::vector& args, bool& SRArgumentSpecified); - //! Reread the configuration file + /** Reread the configuration file */ bool UpdateCTestConfiguration(); - //! Create note from files. + /** Create note from files. */ int GenerateCTestNotesOutput(cmXMLWriter& xml, const VectorOfStrings& files); - //! Check if the argument is the one specified + /** Check if the argument is the one specified */ bool CheckArgument(const std::string& arg, const char* varg1, const char* varg2 = CM_NULLPTR); - //! Output errors from a test + /** Output errors from a test */ void OutputTestErrors(std::vector const& process_output); - //! Handle the --test-action command line argument + /** Handle the --test-action command line argument */ bool HandleTestActionArgument(const char* ctestExec, size_t& i, const std::vector& args); - //! Handle the --test-model command line argument + /** Handle the --test-model command line argument */ bool HandleTestModelArgument(const char* ctestExec, size_t& i, const std::vector& args);