system

http.wake

runner.wake

tuple Usage

Unknown quantities are 0

Parameters: Status: Integer,  Runtime: Double,  CPUtime: Double,  MemBytes: Integer,  InBytes: Integer,  OutBytes: Integer

Return Type: Usage

def getUsageThreads (Usage _ run cpu _ _ _: Usage): Double

No description for this feature yet.

Parameters: Usage

Return Type: Double

tuple RunnerInput

RunnerInput is a subset of the fields supplied in the execution Plan

Parameters: Label: String,  Command: List String,  Visible: List Path,  Environment: List String,  Directory: String,  Stdin: String,  Resources: List String,  Prefix: String,  Record: Usage,  IsAtty: Boolean,  FnInputs: List String,  List String,  FnOutputs: List String,  List String

Return Type: RunnerInput

tuple RunnerOutput

The result returned by a Runner after running a job

Parameters: Inputs: List String,  Outputs: List String,  CleanableOutputs: List String,  Usage: Usage,  RunnerError: Option Error

Return Type: RunnerOutput

tuple Runner

A Runner describes a way to invoke a Plan to get a Job

Parameters: Name: String,  Fn: Job,  RunnerInput,  RunnerOutput

Return Type: Runner

def makeRunner (name: String) (run: Job

makeRunner: Hides some of the boiler plate required to create a runner

This function requires very advanced wake experience and should be used with the greatest amount of caution. Callers must ensure at the very least that run calls primJobLaunch and one of the many job “wait” functions. Historically runners allowed dispatching to an arbirary “base” or “inner” runner. This significantly complicated the system and led to very unexpected interactions. It is recomennded that runners don’t accept an “inner” runner and instead directly call the job primatives. If wrapping is unavoidable then the specific runner being wrapped should be named instead of accepting an arbitrary runner parameter.

localRunner is a good reference implementation of the run function.

Parameters: name: String,  run: Job,  RunnerInput,  RunnerOutput

Return Type: Runner

def makeJSONRunnerPlan (rawScript: String): JSONRunnerPlan

make a JSONRunnerPlan with Nil and (_) as defaults for ExtraArgs and Estimate respectively rawScript: String; the path to the script to run jobs with

Parameters: rawScript: String

Return Type: JSONRunnerPlan

def makeJSONRunner ((JSONRunnerPlan rawScript extraArgs extraEnv estimate): JSONRunnerPlan): Runner

Make a Runner that runs a named script to run jobs plan: JSONRunnerPlan; a tuple containing the arguments for this function

Parameters: JSONRunnerPlan

Return Type: Runner

sources.wake

def files (dir: String) (regexp: RegExp): List String

Find files WARNING! Use of this method can make a build unreproducible. Depending on when the method is invoked, the results may vary! This method is intended to be used by the outputFn of localRunner Jobs.

Parameters: dir: String,  regexp: RegExp

Return Type: List String

def source (file: String): Result Path Error

No description for this feature yet.

Parameters: file: String

Return Type: Result Path Error

def claim (file: String): Result Path Error

Allows claiming of a file so long as the file is within wake’s workspace. Keep in mind that if another job produced this file in the same run of wake, claim will fail. Likewise if you claim a file then any job that produces this file will fail. Claim should be thought of as a “virtual” job and wake demands that all paths be produced by exactly one job, virtual or otherwise.

For source files please use source. For files outside of wake’s workspace please use claimFileAsPath or claimFileAsPathIn. claim is good for claiming artifacts of previous builds that should not be rebuilt during this run.

Parameters: - file: The string giving the path to the file to be claimed

Example: ` claim "build/my_flow/my_step/previous-output.txt" # Claims the file `

Parameters: file: String

Return Type: Result Path Error

def sources (dir: String) (filterRegexp: RegExp): Result (List Path) Error

Find sources files

Parameters: dir: String,  filterRegexp: RegExp

Return Type: Result (List Path) Error

def claimFileAsPath (existingFile: String) (desiredWorkspacePath: String): Result Path Error

This API makes it possible to include a non-source file into a wake build. Generally, one should obtain Paths from sources or as the output of Jobs. This API is useful for things like a command-line-supplied input file.

Parameters: existingFile: String,  desiredWorkspacePath: String

Return Type: Result Path Error

def claimFileAsPathIn (outputDirectory: Path) (existingFile: String) (desiredName: String): Result Path Error

No description for this feature yet.

Parameters: outputDirectory: Path,  existingFile: String,  desiredName: String

Return Type: Result Path Error

job.wake

tuple JobKey

JobKey: The values that the database uses to discern a unique job

If all values of two jobs are identical, then the jobs are considered identical. Used to determine reuse eligibility.

Parameters: dir: String,  stdin: String,  env: String,  cmd: String,  signature: Integer,  visible: String,  isatty: Integer

Return Type: JobKey

def primJobCreate (label: String) (jobKey: JobKey) (keep: Integer) (echo: String) (stdout: String) (stderr: String) (runner_out: String) (runner_err: String): Job

Create/reserve a job handle, parameters aren’t necessarily finalized

Parameters: label: String,  jobKey: JobKey,  keep: Integer,  echo: String,  stdout: String,  stderr: String,  runner_out: String,  runner_err: String

Return Type: Job

def primJobVirtual (job: Job) (stdout: String) (stderr: String) (usage: Usage): Unit

Immediately complete a job with the provided outputs without launching a process

Parameters: job: Job,  stdout: String,  stderr: String,  usage: Usage

Return Type: Unit

def primJobLaunch (job: Job) (jobKey: JobKey) (usage: Usage): Unit

Launch the job via a child process. Values such as command or environment can be freely changed from the initial reservation.

Parameters: job: Job,  jobKey: JobKey,  usage: Usage

Return Type: Unit

def primJobFailLaunch (job: Job) (error: Error): Unit

Complete a job before launch with userland defined failure

Parameters: job: Job,  error: Error

Return Type: Unit

def markJobSetupFailure job err

Wrap primJobFailLaunch in the type signature required to satisfy rmapFail, for cases where a runner fails before delegating to localRunner or anything else which calls primJobLaunch.

Parameters: job: Job,  err: Error

Return Type: Result a Error

def primJobFinish (job: Job) (inputs: String) (outputs: String) (all_outputs: String) (usage: Usage): Unit

Complete a job successfully by providing to the runtime the inputs/outputs/usage of the job

Parameters: job: Job,  inputs: String,  outputs: String,  all_outputs: String,  usage: Usage

Return Type: Unit

def primJobCache (jobKey: JobKey): Pair (List Job) (List (Pair String String))

Look up a job in the local database. Returns a completed Job handle with outputs already resolved if it is already cached

Parameters: jobKey: JobKey

Return Type: Pair (List Job) (List (Pair String String))

def primHash5 a b c d e: Integer

Creates a hash of 5 elements

Parameters: a: a,  b: b,  c: c,  d: d,  e: e

Return Type: Integer

def runJobImp label cmd env dir stdin res usage finputs foutputs vis pers run (LogLevel echo) (LogLevel stdout) (LogLevel stderr) isatty

No description for this feature yet.

Parameters: String,  List String,  List String,  String,  String,  List String,  Usage,  List String,  List String,  List String,  List String,  List Path,  Persistence,  Job,  RunnerInput,  RunnerOutput,  LogLevel,  LogLevel,  LogLevel,  Boolean

Return Type: Job

def runJobWith (Runner _ run) (Plan label cmd vis env dir stdin stdout stderr echo pers res usage finputs foutputs isatty)

No description for this feature yet.

Parameters: Runner,  Plan

Return Type: Job

def setJobTag (key: String) (value: String) (job: Job): Job

Set the value of a tag on a Job This is useful for post-build reflection into the database

Parameters: key: String,  value: String,  job: Job

Return Type: Job

def setJobInspectVisibilityHidden (job: Job): Job

Set a special tag to tell db inspection that this job shouldn’t be shown by default

Parameters: job: Job

Return Type: Job

def getJobReport (job: Job): Result Usage Error

Actual usage of a finished job

Parameters: job: Job

Return Type: Result Usage Error

def getJobRecord (job: Job): Option Usage

From database, available the moment a Job exists

Parameters: job: Job

Return Type: Option Usage

def getJobStdoutRaw (job: Job): Result String Error

No description for this feature yet.

Parameters: job: Job

Return Type: Result String Error

def getJobStderrRaw (job: Job): Result String Error

No description for this feature yet.

Parameters: job: Job

Return Type: Result String Error

def getJobFailedStdoutRaw (job: Job): Result String Error

Gives the full stdout of a job as a string, without any manipulation. Returns the result successfully as long as the job was successfully launched and closed its stdout handle at some point during its execution. This generally occurs by the process simply terminating. The only case where this would return a failure is if the job did not successfully launch.

Parameters: job: Job

Return Type: Result String Error

def getJobFailedStderrRaw (job: Job): Result String Error

Gives the full stderr of a job as a string, without any manipulation. Returns the result successfully as long as the job was successfully launched and closed its stderr handle at some point during its execution. This generally occurs by the process simply terminating. The only case in which this would return a failure is if the job did not successfully launch.

Parameters: job: Job

Return Type: Result String Error

def getJobStdout (job: Job): Result String Error

Gives the job’s stdout if the job exited with an exit code of zero. The output will be manipulated to not contain ANSI escape codes.

Parameters: job: Job

Return Type: Result String Error

def getJobStderr (job: Job): Result String Error

Gives the job’s stderr if the job exited with an exit code of zero. The output will be manipulated to not contain ANSI escape codes.

Parameters: job: Job

Return Type: Result String Error

def getJobFailedStdout (job: Job): Result String Error

Gives the job’s stdout if the job was launched successfully and closed its stdout at some point. The output will be manipulated to not contain ANSI escape codes.

Parameters: job: Job

Return Type: Result String Error

def getJobFailedStderr (job: Job): Result String Error

Gives the job’s stdout if the job was launched successfully and closed its stdout at some point. The output will be manipulated to not contain ANSI escape codes.

Parameters: job: Job

Return Type: Result String Error

def unsafe_getJobRunnerOutput (job: Job): Result String Error

Get the runner output from a job. Runner output is separate from job stdout and is used by the runner infrastructure to report information about how the job was executed, rather than output from the job itself. These reportings are communicated via the fd3 stream, which runner scripts can write to inorder to report information to Wake. Result returns an empty string if there is no runner output, and is also stored in the Wake db. Since runner outputs are not cached, a cached result will have an empty runner output.

Marked unsafe as Runner output is not cached and cannot guarantee reproduciblity.

Parameters: job: Job

Return Type: Result String Error

def unsafe_getJobRunnerError (job: Job): Result String Error

Get the runner error from a job. Runner error is separate from job stderr and is used by the runner infrastructure to report errors that occurred while trying to execute the job, rather than errors from the job itself. Runner scripts as well as runners can write to the fd4 stream to report errors. Result returns an empty string if there is no runner error, and is also stored in the Wake db. Since runner errors are not cached, a cached result will have an empty runner error.

Marked unsafe as Runner error is not cached and cannot guarantee reproduciblity.

Parameters: job: Job

Return Type: Result String Error

def unsafe_reportJobRunnerOutput (job: Job) (output: String): Job

Report a runner output for a job. This is used to report out runner infrastructure information observed from Wake. Similar to runner scripts, runners themselves can write to the fd3 stream to report information via this function. Multiple calls to this function for a specific job will append to the runner output message that is saved to the Wake db.

Marked unsafe as this function should only be called for over-the-wall reporting for runners and because of its uncacheablity as runner outputs are not cached.

Parameters: job: Job,  output: String

Return Type: Job

def unsafe_reportJobRunnerError (job: Job) (error: String): Job

Report a runner error for a job. This is used to report out runner infrastructure errors observed from Wake. Similar to runner scripts, runners themselves can write to the fd4 stream to report errors via this function. Multiple calls to this function for a specific job will append to the runner error message that is saved to the Wake db.

Marked unsafe as this function should only be called for over-the-wall reporting for runners and because of its uncacheablity as runner errors are not cached.

Parameters: job: Job,  error: String

Return Type: Job

def unsafe_getJobRunnerStatusMessage (job: Job): Result (Option String) Error

Get the runner status from a job. The runner status is used to determine if the runner that a job ran on succeeded (None) or failed (Some) and if the latter, why.

Jobs that have a failed runner status are not cached.

Marked unsafe as Runner status is not cached and cannot guarantee reproducibility. In general, this function should only be called by functions which construct and/or publish an execution report, without the downstream logic depending on the contents of that report.

Parameters: job: Job

Return Type: Result (Option String) Error

def getJobInputs (job: Job): Result (List Path) Error

No description for this feature yet.

Parameters: job: Job

Return Type: Result (List Path) Error

def getJobOutputs (job: Job): Result (List Path) Error

No description for this feature yet.

Parameters: job: Job

Return Type: Result (List Path) Error

def getJobFailedInputs (job: Job): Result (List Path) Error

No description for this feature yet.

Parameters: job: Job

Return Type: Result (List Path) Error

def getJobFailedOutputs (job: Job): Result (List Path) Error

No description for this feature yet.

Parameters: job: Job

Return Type: Result (List Path) Error

def getJobId (job: Job): Integer

No description for this feature yet.

Parameters: job: Job

Return Type: Integer

def getJobDescription (job: Job): String

No description for this feature yet.

Parameters: job: Job

Return Type: String

def getJobOutput (job: Job): Result Path Error

No description for this feature yet.

Parameters: job: Job

Return Type: Result Path Error

def isJobOk (job: Job): Boolean

No description for this feature yet.

Parameters: job: Job

Return Type: Boolean

def getJobStatus (job: Job): Status

No description for this feature yet.

Parameters: job: Job

Return Type: Status

def access (file: String) (mode: Integer): Boolean

No description for this feature yet.

Parameters: file: String,  mode: Integer

Return Type: Boolean

job_cache_runner.wake

def mkJobCacheRunner (hashFn: RunnerInput

wakeroot is the absolute sandbox-path from which input and output files will be interpreted as being relative to if they’re in fact relative.

Parameters: RunnerInput,  Result String Error,  String,  Runner

Return Type: Runner

remote_cache_runner.wake

environment.wake

topic path: String

A topic used to globally add directories to the default PATH of a Plans

topic environment: String

A topic used to globally add variables to the default environment of Plans

def getenv (key: String): Option String

getenv: access environment variables provided to the wake executable Use of this function can lead to unnecessary rebuilds!

Parameters: key: String

Return Type: Option String

def getEnvironment (key: String) (environment: List String): Option String

Retrieve the value for ‘key’ from a KEY=VALUE environment list

Parameters: key: String,  environment: List String

Return Type: Option String

def unsetEnvironment (key: String) (environment: List String): List String

Remove a key from a KEY=VALUE environment list

makePlan … | editPlanEnvironment (unsetEnvironment “JAVA_HOME”) | …

Parameters: key: String,  environment: List String

Return Type: List String

def setEnvironment (key: String) (value: String) (environment: List String): List String

Set key=value in an environment list, removing all prior values for that key

makePlan … | editPlanEnvironment (setEnvironment “HELLO” “world”) | …

Parameters: key: String,  value: String,  environment: List String

Return Type: List String

def editEnvironment (key: String) (fn: Option String

Update a key’s value in a KEY=VALUE environment list All prior values for that key are rmeoved Only the first match (if any) is supplied to fn

Parameters: key: String,  fn: Option String,  Option String,  environment: List String

Return Type: List String

def addEnvironmentPath (path: String) (environment: List String): List String

Add a component to the PATH in a KEY=VALUE environment

makePlan … | editPlanEnvironment (addEnvironmentPath “/usr/local/bin”) | …

Parameters: path: String,  environment: List String

Return Type: List String

def addEnvironmentPathOpt (pathopt: Option String) (environment: List String): List String

Optionally add a component to the PATH in a KEY=VALUE environment

Parameters: pathopt: Option String,  environment: List String

Return Type: List String

remote_cache_api.wake

path.wake

def simplify (path: String): String

Simplify away the ..s and .s in a String

Parameters: path: String

Return Type: String

def sortPaths (paths: List Path): List Path

No description for this feature yet.

Parameters: paths: List Path

Return Type: List Path

def in (dir: String) (path: String): String

Concatenate two paths in “foo” “bar” => “foo/bar” in “foo” “/bar ” => “/bar” in “/foo” “bar” => “/foo/bar” in “foo” “../bar” => “bar”

Parameters: dir: String,  path: String

Return Type: String

def relative (dir: String) (path: String): String

Reframe path into a form accesible relative to dir For example: relative “bin” “bin/usr” => “usr” relative “bin” “bin” => “.” relative “bin” “hax” => “../hax”

Parameters: dir: String,  path: String

Return Type: String

target whichIn (path: String) (exec: String): String

Locate an executable in the search path

def which (exec: String): String

No description for this feature yet.

Parameters: exec: String

Return Type: String

target whichInEnvPath (exec: String): Option String

Locate an executable in the users env PATH

def basename (file: String): String

Remove any leading directories from file.

Parameters: - file: The filename to simplify

Guarantees: - The resulting String contains no ‘/’s

` basename "abc/def"  = "def" basename "abc/def/" = "def" basename "/foo/bar" = "bar" basename "/foo"     = "foo" basename "foo-bar"  = "foo-bar" `

Parameters: file: String

Return Type: String

def dirname (file: String): String

Extract the directory name from file.

Parameters: - file: The filename to simplify

Guarantees: - The resulting String is non-empty

` dirname "foo/bar"  = "foo" dirname "bar"      = "." dirname "/bar"     = "/" dirname "/foo/bar" = /foo" `

Parameters: file: String

Return Type: String

def isPathDir (path: Path): Boolean

No description for this feature yet.

Parameters: path: Path

Return Type: Boolean

def getPathParent (path: Path): Path

No description for this feature yet.

Parameters: path: Path

Return Type: Path

target markFileCleanable (filepath: String): Result Unit Error

Allow an untracked file to be removed via wake –clean

plan.wake

tuple Plan

A Plan describes a not-yet-executed Job

Parameters: Label: String,  Command: List String,  Visible: List Path,  Environment: List String,  Directory: String,  Stdin: String,  Stdout: LogLevel,  Stderr: LogLevel,  Echo: LogLevel,  Persistence: Persistence,  Resources: List String,  Usage: Usage,  FnInputs: List String,  List String,  FnOutputs: List String,  List String,  IsAtty: Boolean

Return Type: Plan

def getPlanOnce p

No description for this feature yet.

Parameters: p: Plan

Return Type: Boolean

def getPlanKeep p

No description for this feature yet.

Parameters: p: Plan

Return Type: Boolean

def getPlanShare p

No description for this feature yet.

Parameters: p: Plan

Return Type: Boolean

def setPlanFilterOutputs (filterFn: (file: String)

Sets the FnOutputs field in a Plan by using the given filter function to filter out unneeded files created during a job. This function is recommended over directly setting the FnOutputs field with setPlanFnOutputs.

Parameters: - filterFn: Determines whether to keep a file that was created or not. True means keep the file.

Parameters: filterFn: file: String,  Boolean,  Plan

Return Type: Plan

def setPlanOnce v p

If Once is set to False, no job deduplication is performed and so it must not write any files (stdout/stderr are fine) or be guaranteed to only be encountered once in any wake execution anyway.

Parameters: v: Boolean,  p: Plan

Return Type: Plan

def setPlanKeep v p

No description for this feature yet.

Parameters: v: Boolean,  p: Plan

Return Type: Plan

def setPlanShare v p

No description for this feature yet.

Parameters: v: Boolean,  p: Plan

Return Type: Plan

def prependPlanPath (value: String) (plan: Plan): Plan

Prepend ‘value’ to the Plan’s ‘PATH’ environment value

Parameters: value: String,  plan: Plan

Return Type: Plan

def setPlanEnvVar (name: String) (value: String) (plan: Plan): Plan

Set an environment variable in a Plan

Parameters: name: String,  value: String,  plan: Plan

Return Type: Plan

def editPlanOnce (f: Boolean

If Once is set to False, no job deduplication is performed and so it must not write any files (stdout/stderr are fine) or be guaranteed to only be encountered once in any wake execution anyway.

Parameters: f: Boolean,  Boolean,  Plan

Return Type: Plan

def editPlanKeep (f: Boolean

No description for this feature yet.

Parameters: f: Boolean,  Boolean,  Plan

Return Type: Plan

def editPlanShare (f: Boolean

No description for this feature yet.

Parameters: f: Boolean,  Boolean,  Plan

Return Type: Plan

def getPlanHash (plan: Plan): Integer

Get a unique hash-code for the job

Parameters: plan: Plan

Return Type: Integer

def makePlan (label: String) (visible: List Path) (command: String): Plan

Create a labeled shell plan.

Parameters: label: String,  visible: List Path,  command: String

Return Type: Plan

def makeExecPlan (cmd: List String) (visible: List Path): Plan

Set reasonable defaults for all Plan arguments

Parameters: cmd: List String,  visible: List Path

Return Type: Plan

def makeShellPlan (script: String) (visible: List Path): Plan

No description for this feature yet.

Parameters: script: String,  visible: List Path

Return Type: Plan

io.wake

tuple Permission

The various flags of a given file permission.

Parameters: Read: Boolean,  Write: Boolean,  Execute: Boolean

Return Type: Permission

def perm2bits (perm: Permission)

Converts a Permission tuple to a masked Linux permission bit field.

perm2bits (Permission False True True) -> 3 perm2bits (Permission True True False) -> 6

Parameters: perm: Permission

Return Type: Integer

def bits2perm (bits: Integer)

Converts a masked Linux permission bit field to a Permission tuple

bits2perm 3 -> (Permission False True True) bits2perm 6 -> (Permission True True False)

Parameters: bits: Integer

Return Type: Permission

tuple Mode

The full permission set of a given Path

Parameters: User: Permission,  Group: Permission,  Other: Permission

Return Type: Mode

def bits2mode (bits: Integer)

Converts an unmasked permission bit field into a Mode tuple

bits2mode 365 -> Mode (Permission True False True) (Permission True False True) (Permission True False True)

Parameters: bits: Integer

Return Type: Mode

def mode2bits (mode: Mode)

Converts Mode tuple into an unmasked permission bit field

mode2bits Mode (Permission True False True) (Permission True False True) (Permission True False True) -> 365

Parameters: mode: Mode

Return Type: Integer

tuple Stat

The system Stat of a given Path

Parameters: Type: PathType,  Mode: Mode,  SizeBytes: Integer

Return Type: Stat

target stat (path: Path): Result Stat Error

Returns the system Stat for a given path

target unsafe_stat (path: String): Result Stat Error

Returns the system Stat for a given path string. Prefer stat instead

Should only be used in rare cases where wake invariants are upheld by the caller

def read (path: Path): Result String Error

Read the file contents of a Path

Parameters: path: Path

Return Type: Result String Error

def write (path: String) (content: String): Result Path Error

Create all directories and the named file. The content string is written verbatim with no processing. For example, a final terminating newline character is not appended to the end of the string.

Parameters: path: String,  content: String

Return Type: Result Path Error

def writeTempFile (prefix: String) (content: String): Result Path Error

Writes a string to an intermediate file that will not conflict with other files.

Identical prefix+files will be automatically deduplicated

Parameters: prefix: String,  content: String

Return Type: Result Path Error

def writeIn (parent: Path) (mode: Integer) (name: String) (content: String): Result Path Error

Create a file with the given mode in the specified directory

Parameters: parent: Path,  mode: Integer,  name: String,  content: String

Return Type: Result Path Error

def installAs (dest: String) (file: Path): Result Path Error

installAs: copy a file to a specified destination

Parameters: dest: String,  file: Path

Return Type: Result Path Error

def installIn (toRoot: String) (fromRoot: String) (sourcePath: Path): Result Path Error

Copy a file from one directory subtree to another installIn “/to” “from” “from/subdir/file” => “/to/subdir/file” installIn “/to” “.” “from/subdir/file” => “/to/from/subdir/file” installIn “/to” “/from” “/from/subdir/file” => “/to/subdir/file” installIn “/to” “/” “/from/subdir/file” => “/to/from/subdir/file” These fail: installIn “/to” “from” “subdir/file” installIn “/to” “/from” “/subdir/file” installIn “/to” “from” “/from/subdir/file” installIn “/to” “/from” “from/subdir/file”

Parameters: toRoot: String,  fromRoot: String,  sourcePath: Path

Return Type: Result Path Error

def mkdirIn (parent: Path) (mode: Integer) (name: String): Result Path Error

Create a directory in the parent

Parameters: parent: Path,  mode: Integer,  name: String

Return Type: Result Path Error

def mkdir (path: String): Result Path Error

Make all every element in the directory path with mode 0755

Parameters: path: String

Return Type: Result Path Error

remote_cache_api_test.wake