From 74266a6e650f019063cdcd1c9a7bd26d8f99041b Mon Sep 17 00:00:00 2001 From: Mikko Rasa Date: Tue, 14 Nov 2006 21:39:43 +0000 Subject: [PATCH] Add comments --- source/action.cpp | 3 ++ source/action.h | 11 +++++++ source/analyzer.cpp | 18 ++++++++++++ source/analyzer.h | 11 ++++--- source/archive.h | 3 ++ source/builder.cpp | 61 +++++++++++++++++++++++++++++++-------- source/builder.h | 7 +++-- source/buildinfo.cpp | 10 +++++++ source/buildinfo.h | 4 +++ source/compile.h | 3 ++ source/component.cpp | 6 ++++ source/component.h | 7 +++++ source/config.cpp | 26 +++++++++++++++++ source/config.h | 8 ++++- source/copy.cpp | 5 +++- source/copy.h | 6 ++++ source/executable.cpp | 7 +++++ source/executable.h | 4 +++ source/externalaction.cpp | 6 +++- source/externalaction.h | 3 ++ source/header.h | 6 ++++ source/install.h | 3 ++ source/link.h | 3 ++ source/misc.cpp | 8 +++-- source/objectfile.cpp | 12 ++++++++ source/objectfile.h | 5 +++- source/option.cpp | 10 ------- source/option.h | 22 -------------- source/package.cpp | 31 ++++++++++++++++++++ source/package.h | 7 +++++ source/packageref.cpp | 5 ++++ source/packageref.h | 3 ++ source/sharedlibrary.h | 4 +++ source/sourcefile.cpp | 4 +++ source/sourcefile.h | 5 +++- source/staticlibrary.h | 3 ++ source/systemlibrary.h | 3 ++ source/target.cpp | 29 +++++++++++++++++++ source/target.h | 9 ++++++ source/virtualtarget.cpp | 6 ++++ source/virtualtarget.h | 5 +++- 41 files changed, 334 insertions(+), 58 deletions(-) delete mode 100644 source/option.cpp delete mode 100644 source/option.h diff --git a/source/action.cpp b/source/action.cpp index 9ec8087..782546a 100644 --- a/source/action.cpp +++ b/source/action.cpp @@ -5,6 +5,9 @@ using namespace std; +/** +Annouces the action by printing out the package name, tool and target name. +*/ void Action::announce(const string &pkg, const string &tool, const string &tgt) { ostringstream line; diff --git a/source/action.h b/source/action.h index 60d1450..5877e89 100644 --- a/source/action.h +++ b/source/action.h @@ -6,12 +6,23 @@ class Builder; +/** +Actions are executed to rebuild targets. +*/ class Action { public: + /// Emitted when the action has finished sigc::signal signal_done; + /** + Checks whether the action is done and emits signal_done if it is. + + @return 0 on successful completion, 1 on error, -1 if the action is still + executing + */ virtual int check()=0; + virtual ~Action() { } protected: Builder &builder; diff --git a/source/analyzer.cpp b/source/analyzer.cpp index 21ed52c..e2b25bd 100644 --- a/source/analyzer.cpp +++ b/source/analyzer.cpp @@ -14,10 +14,14 @@ using namespace Msp; Analyzer::Analyzer(Builder &b): builder(b), + mode(DEPS), max_depth(0), full_paths(false) { } +/** +Performs the analysis and prints out the resulting dependency tree. +*/ void Analyzer::analyze() { TableRow row; @@ -32,16 +36,25 @@ void Analyzer::analyze() print_table(); } +/** +Adds rows to the table for the given target and it' dependencies. + +@param tgt Target to be processed +@param depth Recursion level of the target (top level is 0) +*/ void Analyzer::build_depend_table(Target &tgt, unsigned depth) { if(mode!=REBUILD && mode!=ALLDEPS) { + // Skip trivial targets if(dynamic_cast(&tgt)) return build_depend_table(*tgt.get_depends().front(), depth); else if(dynamic_cast(&tgt)) return build_depend_table(*tgt.get_depends().front(), depth); } else if(mode==REBUILD && !tgt.get_rebuild()) + /* All targets that depend on to-be-built targets will be rebuilt + themselves, so we cn stop here. */ return; TableRow row; @@ -74,16 +87,21 @@ void Analyzer::build_depend_table(Target &tgt, unsigned depth) if(!max_depth || depth col_width; + // Determine column widths for(Table::const_iterator i=table.begin(); i!=table.end(); ++i) { if(col_width.size()size()) diff --git a/source/analyzer.h b/source/analyzer.h index 6c7b9dc..c5c6ba2 100644 --- a/source/analyzer.h +++ b/source/analyzer.h @@ -8,15 +8,18 @@ class Builder; class Target; +/** +Performs various kinds of dependency analysis on the build tree. +*/ class Analyzer { public: enum Mode { - DEPS, - ALLDEPS, - REBUILD, - RDEPS + DEPS, /// Skip over "trivial" targets such as Install and Compile + ALLDEPS, /// Print out absolutely every target + REBUILD, /// Print targets that are going to be rebuilt + RDEPS /// Print targets that depend on the given targets (NYI) }; Analyzer(Builder &); diff --git a/source/archive.h b/source/archive.h index 49b5fe0..e95749e 100644 --- a/source/archive.h +++ b/source/archive.h @@ -5,6 +5,9 @@ class StaticLibrary; +/** +Creates an archive of object files, a.k.a. static library. +*/ class Archive: public ExternalAction { public: diff --git a/source/builder.cpp b/source/builder.cpp index 5a1d624..c271c2b 100644 --- a/source/builder.cpp +++ b/source/builder.cpp @@ -171,7 +171,9 @@ Target *Builder::get_target(const string &n) /** Tries to locate a header included from a given location and with a given include -path. Considers known targets as well as existing files. +path. Considers known targets as well as existing files. If a matching target +is not found but a file exists, a new SystemHeader target will be created and +returned. */ Target *Builder::get_header(const string &include, const string &from, const list &path) { @@ -201,6 +203,11 @@ Target *Builder::get_header(const string &include, const string &from, const lis return 0; } +/** +Tries to locate a library with the given library path. Considers known targets +as well as existing files. If a matching target is not found but a file exists, +a new SystemLibrary target will be created and returned. +*/ Target *Builder::get_library(const string &lib, const list &path) { string hash(8, 0); @@ -350,6 +357,13 @@ void Builder::usage(const char *argv0, bool brief) } } +/** +Loads the given build file. + +@param fn Path to the file + +@return 0 on success, -1 if the file could not be opened +*/ int Builder::load_build_file(const Path::Path &fn) { ifstream in(fn.str().c_str()); @@ -363,6 +377,12 @@ int Builder::load_build_file(const Path::Path &fn) return 0; } +/** +Creates targets for all packages and prepares them for building. + +@return 0 if everything went ok, -1 if something bad happened and a build + shouldn't be attempted +*/ int Builder::create_targets() { Target *world=new VirtualTarget(*this, "world"); @@ -390,6 +410,7 @@ int Builder::create_targets() const ComponentList &components=i->second->get_components(); for(ComponentList::const_iterator j=components.begin(); j!=components.end(); ++j) { + // Collect all files belonging to the component PathList files; const PathList &sources=j->get_sources(); for(PathList::const_iterator k=sources.begin(); k!=sources.end(); ++k) @@ -413,17 +434,15 @@ int Builder::create_targets() { string basename=(*k)[-1]; string ext=Path::splitext(basename).ext; - if(ext==".cpp" || ext==".c") + if((ext==".cpp" || ext==".c") && build_exe) { - if(build_exe) - { - SourceFile *src=new SourceFile(*this, &*j, k->str()); - add_target(src); - - ObjectFile *obj=new ObjectFile(*this, *j, *src); - add_target(obj); - objs.push_back(obj); - } + SourceFile *src=new SourceFile(*this, &*j, k->str()); + add_target(src); + + // Compile sources + ObjectFile *obj=new ObjectFile(*this, *j, *src); + add_target(obj); + objs.push_back(obj); } else if(ext==".h") { @@ -433,6 +452,8 @@ int Builder::create_targets() hdr=new Header(*this, &*j, k->str()); add_target(hdr); } + + // Install headers if requested if(!j->get_install_headers().empty()) { Path::Path inst_path=inst_base/"include"/j->get_install_headers()/basename; @@ -493,6 +514,7 @@ int Builder::create_targets() } } + // Find dependencies until no new targets are created while(!new_tgts.empty()) { Target *tgt=new_tgts.front(); @@ -502,7 +524,8 @@ int Builder::create_targets() new_tgts.push_back(tgt); } - for(list::iterator i=what_if.begin(); i!=what_if.end(); ++i) + // Apply what-ifs + for(StringList::iterator i=what_if.begin(); i!=what_if.end(); ++i) { Target *tgt=get_target((cwd/ *i).str()); if(!tgt) @@ -513,6 +536,7 @@ int Builder::create_targets() tgt->touch(); } + // Make the cmdline target depend on all targets mentioned on the command line Target *cmdline=new VirtualTarget(*this, "cmdline"); add_target(cmdline); world->add_depend(cmdline); @@ -534,6 +558,10 @@ int Builder::create_targets() return 0; } +/** +Check if a header exists, either as a target or a file. Either an existing +target or a new SystemHeader target will be returned. +*/ Target *Builder::check_header(const Msp::Path::Path &fn) { Target *tgt=get_target(fn.str()); @@ -547,12 +575,18 @@ Target *Builder::check_header(const Msp::Path::Path &fn) return 0; } +/** +Adds a target to both the target map and the new target queue. +*/ void Builder::add_target(Target *t) { targets.insert(TargetMap::value_type(t->get_name(), t)); new_tgts.push_back(t); } +/** +Updates a hash with a string. This is used from get_header and get_library. +*/ void Builder::update_hash(string &hash, const string &value) { for(unsigned i=0; iget_config(); diff --git a/source/builder.h b/source/builder.h index 786b48c..1016498 100644 --- a/source/builder.h +++ b/source/builder.h @@ -14,12 +14,15 @@ class Analyzer; class Package; +/** +The main application class. Controls and owns everything. Rules the world. +*/ class Builder: public Msp::Application { public: Builder(int, char **); - unsigned get_verbose() const { return verbose; } - bool get_dry_run() const { return dry_run; } + unsigned get_verbose() const { return verbose; } + bool get_dry_run() const { return dry_run; } bool get_build_all() const { return build_all; } Package *get_package(const std::string &); Target *get_target(const std::string &); diff --git a/source/buildinfo.cpp b/source/buildinfo.cpp index f96820b..de111e9 100644 --- a/source/buildinfo.cpp +++ b/source/buildinfo.cpp @@ -3,6 +3,9 @@ using namespace Msp; +/** +Adds another BuildInfo to the end of this one. +*/ void BuildInfo::add(const BuildInfo &bi) { cflags.insert(cflags.end(), bi.cflags.begin(), bi.cflags.end()); @@ -13,6 +16,9 @@ void BuildInfo::add(const BuildInfo &bi) libs.insert(libs.end(), bi.libs.begin(), bi.libs.end()); } +/** +Makes sure there are no duplicate entries in the lists. +*/ void BuildInfo::unique() { unique(cflags); @@ -23,6 +29,10 @@ void BuildInfo::unique() unique(libs); } +/** +Removes any duplicate entries from a list, leaving only the first one. The +order of other elements is preserved. O(n²) efficiency. +*/ void BuildInfo::unique(StringList &l) { StringList l2; diff --git a/source/buildinfo.h b/source/buildinfo.h index ccd4b86..10fd3be 100644 --- a/source/buildinfo.h +++ b/source/buildinfo.h @@ -6,6 +6,10 @@ #include #include "misc.h" +/** +Stores information about compiler command line parameters in a more abstract +form. Allows combining with other BuildInfos to support package dependencies. +*/ class BuildInfo { public: diff --git a/source/compile.h b/source/compile.h index 5e0d47f..fd6ae8b 100644 --- a/source/compile.h +++ b/source/compile.h @@ -7,6 +7,9 @@ class Component; class ObjectFile; +/** +Compiles a source file into an object file. +*/ class Compile: public ExternalAction { public: diff --git a/source/component.cpp b/source/component.cpp index 6d02ad3..97fdacd 100644 --- a/source/component.cpp +++ b/source/component.cpp @@ -10,12 +10,18 @@ Component::Component(Package &p, Type t, const string &n): install(false) { } +/** +Tries to resolve all references to packages. +*/ void Component::resolve_refs() { for(PkgRefList::iterator i=requires.begin(); i!=requires.end(); ++i) i->resolve(); } +/** +Prepares the build information for building. +*/ void Component::create_build_info() { build_info.add(pkg.get_build_info()); diff --git a/source/component.h b/source/component.h index ab39068..663132a 100644 --- a/source/component.h +++ b/source/component.h @@ -10,9 +10,16 @@ class Package; +/** +Components specify things to be built. Each component may build one binary (it +may also build none), as well as install a bunch of headers. Components inherit +dependencies and build info from the package they belong to, and may also add +their own. +*/ class Component { public: + /// Loads a Component from file. Used from Package::Loader. class Loader: public Msp::Parser::Loader { public: diff --git a/source/config.cpp b/source/config.cpp index 61f7322..99e5981 100644 --- a/source/config.cpp +++ b/source/config.cpp @@ -7,11 +7,22 @@ using namespace std; using namespace Msp; +/** +Adds a configuration option. + +@param n Option name +@param v Default value +@param d Description +*/ void Config::add_option(const string &n, const string &v, const string &d) { options.insert(OptionMap::value_type(n, Option(n, v, d))); } +/** +Gets the given option from the configuration. If the option doesn't exist, +an Exception is thrown. +*/ const Config::Option &Config::get_option(const string &name) const { OptionMap::const_iterator i=options.find(name); @@ -21,11 +32,23 @@ const Config::Option &Config::get_option(const string &name) const return i->second; } +/** +Checks whether an option with the given name exists. +*/ bool Config::is_option(const string &name) const { return options.count(name); } +/** +Processes options from the given raw option map. Nonexistent options are +ignored. If any options were changed, the mtime of the configuration is updated +to the current time. + +@param opts A map to process options from + +@return Whether any option values were changed +*/ bool Config::process(const RawOptionMap &opts) { bool changed=false; @@ -46,6 +69,9 @@ bool Config::process(const RawOptionMap &opts) return changed; } +/** +Loads configuration from a file, if it exists. +*/ void Config::load(const Path::Path &fn) { ifstream in(fn.str().c_str()); diff --git a/source/config.h b/source/config.h index 9747d99..355108f 100644 --- a/source/config.h +++ b/source/config.h @@ -6,13 +6,19 @@ #include #include #include -#include "option.h" typedef std::map RawOptionMap; +/** +Manages configuration for a package. A configuration may have an arbitary +amount of options, as well as a modification time (mtime). +*/ class Config { public: + /** + A single configuration option. + */ struct Option { std::string name; diff --git a/source/copy.cpp b/source/copy.cpp index 0607b5d..6ad2a5e 100644 --- a/source/copy.cpp +++ b/source/copy.cpp @@ -25,7 +25,7 @@ Copy::Copy(Builder &b, const Package &pkg, const Path::Path &s, const Path::Path int Copy::check() { - if(!worker) + if(!worker) // True for dry run { signal_done.emit(); return 0; @@ -50,6 +50,7 @@ void Copy::Worker::main() { Path::mkpath(copy.dest.subpath(0, copy.dest.size()-1), 0755); + // Remove old file. Not doing this would cause Bad Stuff when installing libraries. if(unlink(copy.dest.str().c_str())<0 && errno!=ENOENT) { int err=errno; @@ -74,6 +75,7 @@ void Copy::Worker::main() return; } + // Actual transfer loop char buf[16384]; while(!in.eof()) { @@ -81,6 +83,7 @@ void Copy::Worker::main() out.write(buf, in.gcount()); } + // Preserve file permissions struct stat st; Path::stat(copy.src, st); chmod(copy.dest.str().c_str(), st.st_mode&0777); diff --git a/source/copy.h b/source/copy.h index 3f92b15..4e23216 100644 --- a/source/copy.h +++ b/source/copy.h @@ -7,6 +7,9 @@ class Package; +/** +Copies a file to another place. Used by the Install target. +*/ class Copy: public Action { public: @@ -14,6 +17,9 @@ public: int check(); ~Copy(); private: + /** + A worker thread that actually does the data transfer. + */ class Worker: public Msp::Thread { public: diff --git a/source/executable.cpp b/source/executable.cpp index fb1edfb..8f8c9a2 100644 --- a/source/executable.cpp +++ b/source/executable.cpp @@ -16,6 +16,9 @@ Executable::Executable(Builder &b, const Component &c, const list add_depend(*i); } +/** +Finds and adds any required libraries to the dependencies. +*/ void Executable::find_depends() { const list &libs=comp.get_build_info().libs; @@ -34,6 +37,10 @@ Action *Executable::build() return Target::build(new Link(builder, *this));; } +/** +Returns the name for the executable. We can't do this in the constructor since +we need to pass the value to the Target c'tor. +*/ string Executable::generate_target_name(const Component &c) { string prefix,suffix; diff --git a/source/executable.h b/source/executable.h index 7fefef7..d7d8ebb 100644 --- a/source/executable.h +++ b/source/executable.h @@ -6,6 +6,10 @@ class Component; class ObjectFile; +/** +Produces a binary file, which may be either a standalone executable or a shared +library. +*/ class Executable: public Target { public: diff --git a/source/externalaction.cpp b/source/externalaction.cpp index b86d802..0ae68ff 100644 --- a/source/externalaction.cpp +++ b/source/externalaction.cpp @@ -16,7 +16,7 @@ int ExternalAction::check() } if(!pid) - return 255; + return exit_code; int status; if(waitpid(pid, &status, WNOHANG)==pid) @@ -26,12 +26,16 @@ int ExternalAction::check() exit_code=WEXITSTATUS(status); else exit_code=254; + pid=0; return exit_code; } else return -1; } +/** +Starts the external program. Fill in argv before calling this. +*/ void ExternalAction::launch() { if(builder.get_verbose()>=2) diff --git a/source/externalaction.h b/source/externalaction.h index 86f3275..2ab4ca0 100644 --- a/source/externalaction.h +++ b/source/externalaction.h @@ -6,6 +6,9 @@ #include "action.h" #include "misc.h" +/** +Base class for Actions that want to execute an external program. +*/ class ExternalAction: public Action { public: diff --git a/source/header.h b/source/header.h index c398468..a22c6ce 100644 --- a/source/header.h +++ b/source/header.h @@ -3,6 +3,9 @@ #include "sourcefile.h" +/** +Represents a header file. Mainly exists to give extra information to the user. +*/ class Header: public SourceFile { public: @@ -10,6 +13,9 @@ public: const char *get_type() const { return "Header"; } }; +/** +A header file that doesn't belong to any known package. +*/ class SystemHeader: public Header { public: diff --git a/source/install.h b/source/install.h index 503205a..fd6472f 100644 --- a/source/install.h +++ b/source/install.h @@ -3,6 +3,9 @@ #include "target.h" +/** +Represents the installation of a file. +*/ class Install: public Target { public: diff --git a/source/link.h b/source/link.h index 63ebf35..4848388 100644 --- a/source/link.h +++ b/source/link.h @@ -5,6 +5,9 @@ class Executable; +/** +Links object files and libraries to produce an executable. +*/ class Link: public ExternalAction { public: diff --git a/source/misc.cpp b/source/misc.cpp index 37616a9..35953a7 100644 --- a/source/misc.cpp +++ b/source/misc.cpp @@ -6,7 +6,11 @@ using namespace std; using namespace Msp; -string run_command(const list &argv) +/** +Runs a command and returns its output as a string. The exit status of the +command is lost. +*/ +string run_command(const StringList &argv) { int pfd[2]; pipe(pfd); @@ -17,7 +21,7 @@ string run_command(const list &argv) if(pid==0) { char *argv_[argv.size()+1]; - for(CountingIterator::const_iterator> i=argv.begin(); i!=argv.end(); ++i) + for(CountingIterator i=argv.begin(); i!=argv.end(); ++i) argv_[i.count()]=strdup(i->c_str()); argv_[argv.size()]=0; close(pfd[0]); diff --git a/source/objectfile.cpp b/source/objectfile.cpp index 874f069..2aab39b 100644 --- a/source/objectfile.cpp +++ b/source/objectfile.cpp @@ -19,6 +19,12 @@ ObjectFile::ObjectFile(Builder &b, const Component &c, SourceFile &src): add_depend(&src); } +/** +Processes as many new dependences as possible. Some may be left unprocessed +if their own dependencies are not ready, requiring another call to this +function. Use the get_deps_ready() function to determine whether this is the +case. +*/ void ObjectFile::find_depends() { for(TargetList::iterator i=new_deps.begin(); i!=new_deps.end();) @@ -41,6 +47,9 @@ Action *ObjectFile::build() return Target::build(new Compile(builder, *this)); } +/** +Recursively looks for header targets and adds them as dependencies. +*/ void ObjectFile::find_depends(Target *tgt) { const string &tname=tgt->get_name(); @@ -65,6 +74,9 @@ void ObjectFile::find_depends(Target *tgt) } } +/** +Adds a target to the dependency list as well as the new dependencies list. +*/ void ObjectFile::add_depend(Target *tgt) { Target::add_depend(tgt); diff --git a/source/objectfile.h b/source/objectfile.h index 8306aea..42238e1 100644 --- a/source/objectfile.h +++ b/source/objectfile.h @@ -6,11 +6,14 @@ class Component; class SourceFile; +/** +Object files are compiled from source files. +*/ class ObjectFile: public Target { public: ObjectFile(Builder &, const Component &, SourceFile &); - const char *get_type() const { return "ObjectFile"; } + const char *get_type() const { return "ObjectFile"; } const Component &get_component() const { return comp; } void find_depends(); Action *build(); diff --git a/source/option.cpp b/source/option.cpp deleted file mode 100644 index 8f1a6e9..0000000 --- a/source/option.cpp +++ /dev/null @@ -1,10 +0,0 @@ -#include "option.h" - -using namespace std; - -Option::Option(const string &n, const string &v, const string &d): - name(n), - defv(v), - descr(d), - value(v) -{ } diff --git a/source/option.h b/source/option.h deleted file mode 100644 index cbf1769..0000000 --- a/source/option.h +++ /dev/null @@ -1,22 +0,0 @@ -#ifndef OPTION_H_ -#define OPTION_H_ - -#include - -class Option -{ -public: - Option(const std::string &, const std::string &, const std::string &); - void set_value(const std::string &v) { value=v; } - const std::string &get_value() const { return value; } - const std::string &get_name() const { return name; } - const std::string &get_default_value() const { return defv; } - const std::string &get_description() const { return descr; } -private: - std::string name; - std::string defv; - std::string descr; - std::string value; -}; - -#endif diff --git a/source/package.cpp b/source/package.cpp index 14d2321..14ae5f7 100644 --- a/source/package.cpp +++ b/source/package.cpp @@ -9,6 +9,9 @@ using namespace Msp; #include +/** +Creates a buildable package. +*/ Package::Package(Builder &b, const string &n, const Path::Path &s): builder(b), name(n), @@ -17,11 +20,18 @@ Package::Package(Builder &b, const string &n, const Path::Path &s): build_info_ready(false) { } +/** +Sets the path where the package files were installed. This is only useful for +non-buildable packages that don't use pkg-config. +*/ void Package::set_path(const Msp::Path::Path &p) { path=builder.get_cwd()/p; } +/** +Tries to resolve all references to dependency packages. +*/ void Package::resolve_refs() { for(PkgRefList::iterator i=requires.begin(); i!=requires.end(); ++i) @@ -30,6 +40,9 @@ void Package::resolve_refs() i->resolve_refs(); } +/** +Fills in build info based on configuration. +*/ void Package::create_build_info() { if(build_info_ready) @@ -101,12 +114,21 @@ void Package::create_build_info() build_info_ready=true; } +/** +Processes configuration options that were most likely obtained from the command +line. +*/ void Package::process_options(const RawOptionMap &opts) { if(config.process(opts)) config.save(source/".options.cache"); } +/** +Creates a non-buildable package with the given name. Pkg-config is tried first +to get build information. If it fails, a built-in list of known packages is +consulted. +*/ Package *Package::create(Builder &b, const string &name) { list argv; @@ -120,6 +142,7 @@ Package *Package::create(Builder &b, const string &name) bool need_path=false; if(info.empty()) { + //XXX Put these in an external file if(name=="opengl") info.push_back("-lGL"); else if(name=="pthread") @@ -158,6 +181,9 @@ Package::Package(Builder &b, const string &n, const vector &info): } } +/** +Initializes a buildable package. Mostly adds configuration options. +*/ void Package::init_buildable() { buildable=true; @@ -187,6 +213,11 @@ void Package::init_buildable() config.load(source/".options.cache"); } +/** +Checks which kinds of things the components of this package install. + +@return A bitmask of installed things +*/ unsigned Package::get_install_flags() { unsigned flags=0; diff --git a/source/package.h b/source/package.h index 743a962..3d980f2 100644 --- a/source/package.h +++ b/source/package.h @@ -11,9 +11,16 @@ class Builder; +/** +A package is a distributable piece of software. They consist of one or more +Components and may depend on other packages. Packages also have configuration +to determine where files are installed and which features to include (features +NYI). +*/ class Package { public: + /// Loads a package from a file. class Loader: public Msp::Parser::Loader { public: diff --git a/source/packageref.cpp b/source/packageref.cpp index 0f7dc26..57336a3 100644 --- a/source/packageref.cpp +++ b/source/packageref.cpp @@ -10,6 +10,11 @@ PackageRef::PackageRef(Builder &b, const string &n): package(0) { } +/** +Tries to get the package from Builder if we don't have it already. + +@return The package pointer (0 if the package was not found) +*/ Package *PackageRef::resolve() { if(!package) diff --git a/source/packageref.h b/source/packageref.h index 9698b1e..da25f53 100644 --- a/source/packageref.h +++ b/source/packageref.h @@ -7,6 +7,9 @@ class Builder; class Package; +/** +A proxy class that stores a package name and possibly a pointer to the package. +*/ class PackageRef { public: diff --git a/source/sharedlibrary.h b/source/sharedlibrary.h index 96a38fa..639592d 100644 --- a/source/sharedlibrary.h +++ b/source/sharedlibrary.h @@ -3,6 +3,10 @@ #include "executable.h" +/** +Represents a shared library. Mainly exists to give extra information to the +user. +*/ class SharedLibrary: public Executable { public: diff --git a/source/sourcefile.cpp b/source/sourcefile.cpp index ba37f3f..c4eea79 100644 --- a/source/sourcefile.cpp +++ b/source/sourcefile.cpp @@ -14,6 +14,10 @@ SourceFile::SourceFile(Builder &b, const Component *c, const string &n): comp(c) { } +/** +Parses include directives from the file and looks up the appropriate targets +from Builder. +*/ void SourceFile::find_depends() { ifstream in(name.c_str()); diff --git a/source/sourcefile.h b/source/sourcefile.h index 0bca390..381d593 100644 --- a/source/sourcefile.h +++ b/source/sourcefile.h @@ -5,12 +5,15 @@ class Component; +/** +Represents a C or C++ source file. +*/ class SourceFile: public Target { public: SourceFile(Builder &, const Component *, const std::string &); const StringList &get_includes() const { return includes; } - const char *get_type() const { return "SourceFile"; } + const char *get_type() const { return "SourceFile"; } void find_depends(); Action *build() { return 0; } private: diff --git a/source/staticlibrary.h b/source/staticlibrary.h index 0d1242f..83ae105 100644 --- a/source/staticlibrary.h +++ b/source/staticlibrary.h @@ -6,6 +6,9 @@ class Component; class ObjectFile; +/** +A static library target. +*/ class StaticLibrary: public Target { public: diff --git a/source/systemlibrary.h b/source/systemlibrary.h index bd55429..babd494 100644 --- a/source/systemlibrary.h +++ b/source/systemlibrary.h @@ -3,6 +3,9 @@ #include "target.h" +/** +A library that doesn't belong to any known package. +*/ class SystemLibrary: public Target { public: diff --git a/source/target.cpp b/source/target.cpp index e034288..1f4ace9 100644 --- a/source/target.cpp +++ b/source/target.cpp @@ -8,6 +8,11 @@ using namespace std; using namespace Msp; +/** +Tries to locate a target that will help getting this target built. If all +dependencies are up-to-date, returns this target. If there are no targets +ready to be built (maybe because they are being built right now), returns 0. +*/ Target *Target::get_buildable_target() { bool self_ok=true; @@ -32,17 +37,28 @@ void Target::add_depend(Target *dep) dep->rdepends.push_back(this); } +/** +Prepares the target by recursively preparing dependencies, then checking +whether rebuilding is needed. A flag is used to prevent unnecessary +executions. +*/ void Target::prepare() { if(prepared) return; + prepared=true; for(TargetList::iterator i=depends.begin(); i!=depends.end(); ++i) (*i)->prepare(); check_rebuild(); + } +/** +Returns the number of targets that need to be rebuilt in order to get this +target up-to-date. +*/ unsigned Target::count_rebuild() { if(counted) @@ -55,6 +71,9 @@ unsigned Target::count_rebuild() return count; } +/** +Changes the mtime of the target to the current time. +*/ void Target::touch() { mtime=Time::now(); @@ -82,6 +101,9 @@ void Target::mark_rebuild(const std::string &reason) rebuild_reason=reason; } +/** +Checks if this target needs to be rebuilt and why. +*/ void Target::check_rebuild() { if(!buildable) @@ -105,6 +127,10 @@ void Target::check_rebuild() mark_rebuild("Package options changed"); } +/** +Hooks the target up with the given action, then returns it. This should be +called from the public build() function of buildable targets. +*/ Action *Target::build(Action *action) { building=true; @@ -112,6 +138,9 @@ Action *Target::build(Action *action) return action; } +/** +Handles for the build_done signal of Action. +*/ void Target::build_done() { building=false; diff --git a/source/target.h b/source/target.h index eb46d9f..fa744ac 100644 --- a/source/target.h +++ b/source/target.h @@ -12,6 +12,10 @@ class Package; class Target; typedef std::list TargetList; +/** +Targets make up the build graph. This class is a base for all target types and +handles many common tasks. Most targets are associated with a file. +*/ class Target { public: @@ -27,7 +31,12 @@ public: void add_depend(Target *); virtual void find_depends() { deps_ready=true; } virtual void prepare(); + + /** + Creates and returns an Action suitable for building this target. + */ virtual Action *build()=0; + void reset_count() { counted=false; } virtual unsigned count_rebuild(); void touch(); diff --git a/source/virtualtarget.cpp b/source/virtualtarget.cpp index 074647a..4a272a7 100644 --- a/source/virtualtarget.cpp +++ b/source/virtualtarget.cpp @@ -3,6 +3,9 @@ using namespace std; +/** +Virtual targets are only rebuilt if their dependencies need rebuilding. +*/ void VirtualTarget::check_rebuild() { for(TargetList::iterator i=depends.begin(); (i!=depends.end() && !rebuild); ++i) @@ -10,6 +13,9 @@ void VirtualTarget::check_rebuild() mark_rebuild(Msp::Path::basename((*i)->get_name())+" needs rebuilding"); } +/** +Don't count virtual targets since "building" them causes no action. +*/ unsigned VirtualTarget::count_rebuild() { return Target::count_rebuild()-rebuild; diff --git a/source/virtualtarget.h b/source/virtualtarget.h index baccfa6..65967f2 100644 --- a/source/virtualtarget.h +++ b/source/virtualtarget.h @@ -3,10 +3,13 @@ #include "target.h" +/** +A target that is not associated with any file. +*/ class VirtualTarget: public Target { public: - VirtualTarget(Builder &b, const std::string &n): Target(b,0,n) { } + VirtualTarget(Builder &b, const std::string &n): Target(b, 0, n) { } const char *get_type() const { return "VirtualTarget"; } Action *build() { rebuild=false; return 0; } unsigned count_rebuild(); -- 2.43.0