Annolib programmer’s reference

anno create —Create a new anno object that can be used to query information from an annotation file. The return value is a handle that can be used in a subsequent [$anno …​] call. For example:

$anno agents —Retrieve a list of agents that participated in this build.

$anno comparejobs <field> <jobId> <jobId> —Compare two jobs for sorting by the given field and return -1, 0, or 1 if the first job is earlier, equal to, or later than the second job.

$anno destroy —Release all resources associated with this anno instance and remove the command for controlling it from the interpreter.

$anno duration —Retrieve the length of the build that is described in the anno object. This is the greatest time index seen in the annotation file.

$anno environment —Dump the contents of the environment table, which was built out of the section of the annotation file. The result is a list of name/value pairs similar to [array get]. The list is unordered.

$anno file <command> <filename> —Query the anno object for information about a file referenced by the build.

$anno file isdirectory <filename> —Return a Boolean indicating whether the specified file is a directory or not.

$anno file operations <filename> —Return a Tcl list of lists describing the operations that referenced this file in the build.

$anno file type <filename> —Return the file type for the specified file.

$anno filecount —Retrieve a count of the number of files referenced in Operations in this annotation file.

$anno files —Retrieve a list of the files referenced in Operations in this annotation file.

$anno indexagents —For each agent in the annotation, construct a list of jobs that were run on that agent, sorted in order of time in which they were invoked. This index is stored internally for use by Insight when rendering the annotation.

$anno load <channel> ?count? —Parse ?count? bytes of data from <channel> and create job objects as necessary. The return value is a Boolean indicating whether parsing is complete. If ?count? is not specified, all data is read from <channel>.

$anno loadstring <data> ?done? —Parse the data in <data> and create job objects as necessary. There is no return value. If ?done? is specified, it indicates whether the string represents the end of the XML data.

$anno jobagent <jobId> —Retrieve the name of the agent on which the job ran.

$anno jobcommand <jobId> —Invoke commands on a particular job from the annotation.

$anno job annolength <jobId> —Retrieve the length of the segment of the annotation file that is describing the job.

$anno job annostart <jobId> —Retrieve the start of the segment of the annotation file that is describing the job.

$anno job commands <jobId> —Retrieve a list of the commands that were associated with the job. The result is a list of lists with the following form.

$anno job conflict <jobId> —Return registry conflict information for the specified job.

$anno job conflictfile <jobId> —If the job is a conflict job, retrieve the name of the file that it conflicted over.

$anno job conflicttype <jobId> —If the job is a conflict job, retrieve the type of the conflict.

$anno job deps <jobId> —Retrieve the list of history dependencies for the job. This might be empty if annotation did not include history-level detail or if there were no history dependencies.

$anno job environment <jobId> —Retrieve the environment for the job.

$anno job exitcode <jobId> —Retrieve the exit code for the job.

$anno job finish <jobId> —Retrieve the end time of the job in seconds.

$anno job flags <jobId> —Retrieve the flags for the job as a Tcl list.

$annojob isconflict <jobId> —Return a Boolean indicating whether the job is a conflict job.

$anno job isrerun <jobId> —Return a Boolean indicating whether the job is a rerun job.

$anno job isreverted <jobId> —Return a Boolean indicating whether the job is a reverted job.

$anno job jobcache diffs <jobId> —Retrieve a list of differences that caused a job cache miss. Each entry in the list is itself a list that gives the name of the file, the original state, the new state, and whether the differences were ignored by eMake.

$anno job jobcache length <jobId> —Retrieve the duration of the original uncached run of the job.

$anno job jobcache status <jobId> —Retrieve the job cache status, one of “hit”, “miss”, “newslot”, “rootschanged”, “uncacheable”, or “unneeded”.

$anno job jobcache type <jobId> —Retrieve the type of job caching applied to the job, such as “gcc” or “parse”.

$anno job length <jobId> —Retrieve the duration of the job in seconds. This is equivalent to [$anno job jobId finish] - [$anno job jobId start], but it avoids using Tcl’s [expr] command, so it is much faster.

$anno job make <jobId> —Retrieve the Make instance ID for the Make containing the specified job.

$anno job makefile <jobId> —Retrieve the name of the makefile containing the rule that produced the job, if any.

$anno job name <jobId> —Retrieve the name for the specified job.

$annojob neededby <jobId> —Retrieve the ID of the job that caused the job to be run.

$anno job operations <jobId> —Retrieve the list of Operations performed by the job, in order, as a Tcl list of lists.

$anno job operations -type registry <jobId> —Retrieve the list of registry operations for the specified job.

$anno job partof <jobId> —Retrieve the ID of the job that the job continues. This is valid only for continuation jobs; other jobs will return an empty string.

$anno job rerunjob <jobId> —For conflict jobs, retrieve the job that was used to rerun the job.

$annojob serialorder <jobId> —Retrieve the serial order of the job relative to the other jobs in the build. The first job in the build has serial order 1; the final job in the build has serial order N for a build with N jobs.

$anno job start <jobId> —Retrieve the start time of the job in seconds.

$anno job submakes <jobId> —Retrieve the list of submakes performed by the specified job.

$anno job timing <jobId> —Retrieve the full timing information for the job as a list of lists of the form {start finish agent} {start finish agent} …​. Normally there is only one entry in the list; if the job was restarted because of cluster sharing or agent failure, there are additional entries. Jobs that never ran will return an empty list.

$anno job type <jobId> —Retrieve the type of the specified job.

$anno job waitingjobs <jobId> —Retrieve the list of jobs that waited for the job to complete before running. This might be empty if there are no waiting jobs or if the annotation file did not include waitingJobs annotation.

$anno job writejob <jobId> —For conflict jobs, retrieve the job that wrote the file that the job conflicted over.

$anno jobcount —Return a count of the number of jobs in the annotation.

$anno jobiterbegin —(Deprecated as of version 5.0 ) Initialize the job iterator to the head of the list of jobs in the anno object.

$anno jobitermore —(Deprecated as of version 5.0 ) Return a Boolean indicating whether the next call to [$anno jobiternext] will return a valid job or not. This is used in conjunction with [anno jobiterbegin] and [anno jobiternext] to efficiently iterate through the list of jobs in the anno object (in serial order).

$anno jobiternext —(Deprecated as of version 5.0 ) Retrieve the job with the next highest serial order in the anno object using an iterator initialized with [anno jobiterbegin]. If the iterator has reached the end of the list of jobs, an empty string is returned. Otherwise, the job ID for the next job is returned, and the iterator is advanced one step.

$anno jobs begin —Return an iterator for the first job in the build.

$anno jobs end —Return an iterator referring to the “past-the-end” job in the build—not an actual job, but a hypothetical placeholder for iteration.

$anno jobs next <jobId> —Return the next job in the build after the job given by <jobId>.

$anno jobs prev <jobId> —Return the previous job in the build before the job given by <jobId>.

$anno jobs rbegin —Return an iterator for the last job in the build.

$anno jobs rend —Return an iterator referring to the “before-the-first” job in the build—not an actual job, but a hypothetical placeholder for iteration.

$anno jobsearch <attribute pattern> —Search the jobs in the annotation for jobs that match the criteria.

$anno make <command> <makeId> —Invoke commands on a particular Make from the annotation.

$anno make commandline <makeId> —Retrieve the command line for the specified Make.

$anno make job <makeId> —Retrieve the job ID for the job that spawned the given Make instance or an empty string, if no job spawned the Make.

$anno make level <makeId> —Retrieve the level of the specified Make instance.

$anno make mode <makeId> —Retrieve the emulation mode of the given Make instance.

$anno make workingdir <makeId> —Retrieve the working directory for the specified Make instance.

$anno makecount —Return a count of the number of Makes in the annotation.

$anno metrics —Dump the contents of the metrics table, which was built out of the section of the annotation file. The result is a list of name/value pairs similar to [array get]. The list is unordered.

$anno parseoptions ?optionList? —Query or set the anno object parse options. This controls which portions of the annotation file are processed when [anno load] is invoked.

$anno properties —Dump the contents of the properties table, which was built out of the section of the annotation file. The result is a list of name/value pairs similar to [array get]. The list is unordered.

$anno refcount —Retrieve the reference count from the anno object. For testing only.

$anno rjobiterbegin —(Deprecated as of version 5.0 ) Initialize the job iterator to the end of the list of jobs in the anno object.

$ann rjobitermore —(Deprecated as of version 5.0 ) Return a Boolean indicating whether the next call to [anno rjobiternext] will return a valid job or not. This is used in conjunction with [anno rjobiterbegin] and [anno rjobiternext] to efficiently iterate through the list of jobs in the anno object, in reverse serial order.

$anno rjobiternext —(Deprecated as of version 5.0 ) Retrieve the job with the next lowest serial order in the anno object using an iterator initialized with [anno rjobiterbegin]. If the iterator has reached the end of the list of jobs, an empty string is returned. Otherwise, the job ID for the next job is returned, and the iterator is advanced one step.

$anno sortjobs ?options? <jobList> —Sort the jobs in <jobList> according to the given criteria.

$anno type <command> <type> —Query the aggregate attributes of jobs by type.

$anno type conflicttime <type> —Return the amount of time spent on jobs of this type that were later found to be in conflict.

$anno type jobcount <type> —Return the number of jobs of this type.

$anno type reruntime <type> —Return the amount of time spent on jobs of this type that were rerun jobs.

$anno type revertedtime <type> —Return the amount of time spent on jobs of this type that were later reverted.

$anno type time <type> —Return the amount of time spent on jobs of this type that were not conflict, reverted, or rerun jobs.

$anno types —Retrieve a list of known types of jobs.