path: root/rules/CC/test/RULES

{ "test":
  { "doc": ["A test written in C++"]
  , "tainted": ["test"]
  , "target_fields": ["srcs", "private-hdrs", "private-deps", "data"]
  , "string_fields":
    [ "name"
    , "args"
    , "stage"
    , "pure C"
    , "private-defines"
    , "private-cflags"
    , "private-ldflags"
    ]
  , "config_vars":
    [ "ARCH"
    , "HOST_ARCH"
    , "TARGET_ARCH"
    , "CC"
    , "CXX"
    , "CFLAGS"
    , "CXXFLAGS"
    , "LDFLAGS"
    , "ADD_CFLAGS"
    , "ADD_CXXFLAGS"
    , "ADD_LDFLAGS"
    , "ENV"
    , "BUILD_POSITION_INDEPENDENT"
    , "TEST_ENV"
    , "TIMEOUT_SCALE"
    , "CC_TEST_LAUNCHER"
    , "RUNS_PER_TEST"
    , "ARCH_DISPATCH"
    , "TEST_SUMMARY_EXECUTION_PROPERTIES"
    ]
  , "implicit":
    { "defaults": [["./", "..", "defaults"]]
    , "shell-defaults": [["./", "../../shell", "defaults"]]
    , "runner": ["runner"]
    , "summarizer": [["./", "../../shell/test", "summarizer"]]
    }
  , "field_doc":
    { "name":
      [ "The name of the test"
      , ""
      , "Used to name the test binary as well as for staging the test result"
      ]
    , "args": ["Command line arguments for the test binary"]
    , "srcs":
      [ "The sources of the test binary"
      , ""
      , "The resulting test binary is run in an environment where it can assume"
      , "that the environment variable TEST_TMPDIR points to a"
      , "directory that may be used exclusively by this test."
      , "For convenience, the environment variable TMPDIR is also set to TEST_TMPDIR."
      , ""
      , "This running of the test is carried out by the implicit dependency"
      , "on the target \"runner\". By setting this target in the target layer"
      , "of this rules repository (instead of letting it default to the"
      , "respective file), the C/C++ test environment can be modified globally."
      ]
    , "private-hdrs":
      [ "Any additional header files that need to be present when compiling"
      , "the test binary."
      ]
    , "private-defines":
      [ "List of defines set for source files local to this target."
      , "Each list entry will be prepended by \"-D\"."
      ]
    , "private-cflags":
      ["List of compile flags set for source files local to this target."]
    , "private-ldflags":
      [ "Additional linker flags for linking external libraries (not built"
      , "by this tool, typically system libraries)."
      ]
    , "stage":
      [ "The logical location of all header and source files."
      , "Individual directory components are joined with \"/\"."
      ]
    , "data": ["Any files the test binary needs access to when running"]
    , "defaults": ["The C/C++ toolchain to use"]
    , "shell-defaults":
      ["The shell toolchain to use PATH from for calling the summary action"]
    , "runner":
      [ "The test runner which starts the actual test binary after providing"
      , "the respective environment. The runner also takes care of capturing"
      , "stdout/stderr and timing information."
      ]
    , "summarizer":
      [ "Tool to aggregate the results of individual test runs (for flakyness"
      , "detection) to an overall test result. If more fields than the result"
      , "itself is needed, those can be specified using the \"summarizer\" rule."
      ]
    }
  , "config_doc":
    { "CC": ["The name of the C compiler to be used."]
    , "CXX": ["The name of the C++ compiler to be used."]
    , "CFLAGS":
      [ "The flags for CC to be used instead of the default ones"
      , "taken from the [\"CC\", \"defaults\"] target"
      ]
    , "CXXFLAGS":
      [ "The flags for CXX to be used instead of the default ones"
      , "taken from the [\"CC\", \"defaults\"] target"
      ]
    , "LDFLAGS":
      [ "The linker flags do be used instead of the default ones"
      , "taken from the [\"CC\", \"defaults\"] target"
      ]
    , "ADD_CFLAGS":
      [ "The flags to add to the default ones for CC"
      , "taken from the [\"CC\", \"defaults\"] target"
      ]
    , "ADD_CXXFLAGS":
      [ "The flags to add to the default ones for CXX"
      , "taken from the [\"CC\", \"defaults\"] target"
      ]
    , "ADD_LDFLAGS":
      [ "The linker flags to add to the default ones"
      , "taken from the [\"CC\", \"defaults\"] target"
      ]
    , "ENV": ["The environment for any action generated."]
    , "BUILD_POSITION_INDEPENDENT": ["Build with -fPIC."]
    , "TEST_ENV": ["The environment for executing the test runner."]
    , "TIMEOUT_SCALE":
      ["Factor on how to scale the timeout for this test. Defaults to 1.0."]
    , "CC_TEST_LAUNCHER":
      [ "List of strings representing the launcher that is prepend to the"
      , "command line for running the test binary."
      ]
    , "RUNS_PER_TEST":
      [ "The number of times the test should be run in order to detect flakyness."
      , "If set, no test action will be taken from cache."
      , ""
      , "Test runs are summarized by the [\"shell/test\", \"summarizer\"] that"
      , "is also used by shell tests."
      ]
    , "TARGET_ARCH":
      [ "The architecture to build the test for."
      , ""
      , "Will only be honored, if that architecture is available in the"
      , "ARCH_DISPATCH map. Otherwise, the test will be built for and run"
      , "on the host architecture."
      ]
    , "ARCH_DISPATCH":
      [ "Map of architectures to execution properties that ensure execution"
      , "on that architecture. Only the actual test binary will be run with"
      , "the specified execution properties (i.e., on the target architecture);"
      , "all building will be done on the host architecture."
      ]
    , "TEST_SUMMARY_EXECUTION_PROPERTIES":
      [ "Additional remote-execution properties for the test-summarizing action"
      , "in case RUNS_PER_TEST is set; defaults to the empty map."
      ]
    }
  , "artifacts_doc":
    [ "result: the result of this test (\"PASS\" or \"FAIL\"); useful for"
    , "        generating test reports."
    , "stdout/stderr: Any output the invocation of the test binary produced on"
    , "        the respective file descriptor"
    , "time-start/time-stop: The time (decimally coded) in seconds since the"
    , "        epoch when the test invocation started and ended."
    , "pwd:     the directory in which the test was carried out"
    ]
  , "runfiles_doc":
    [ "A tree consisting of the artifacts staged at the name of the test."
    , "As the built-in \"install\" rule only takes the runfiles of its"
    , "\"private-deps\" argument, this gives an easy way of defining test"
    , "suites."
    ]
  , "imports":
    { "artifacts": ["./", "../..", "field_artifacts"]
    , "runfiles": ["./", "../..", "field_runfiles"]
    , "host transition": ["transitions", "maybe for host"]
    , "stage": ["./", "../..", "stage_singleton_field"]
    , "run_test": "run_test"
    , "field_list": ["", "field_list_provider"]
    }
  , "config_transitions":
    { "defaults": [{"type": "CALL_EXPRESSION", "name": "host transition"}]
    , "private-deps": [{"type": "CALL_EXPRESSION", "name": "host transition"}]
    , "data": [{"type": "CALL_EXPRESSION", "name": "host transition"}]
    , "runner": [{"type": "CALL_EXPRESSION", "name": "host transition"}]
    }
  , "expression":
    { "type": "let*"
    , "bindings":
      [ [ "name"
        , { "type": "assert_non_empty"
          , "msg": "A non-empty name has to be provided for binaries"
          , "$1": {"type": "join", "$1": {"type": "FIELD", "name": "name"}}
          }
        ]
      , ["pure C", {"type": "FIELD", "name": "pure C"}]
      , [ "stage"
        , { "type": "join"
          , "separator": "/"
          , "$1": {"type": "FIELD", "name": "stage"}
          }
        ]
      , [ "srcs"
        , { "type": "to_subdir"
          , "subdir": {"type": "var", "name": "stage"}
          , "$1":
            { "type": "let*"
            , "bindings": [["fieldname", "srcs"]]
            , "body": {"type": "CALL_EXPRESSION", "name": "artifacts"}
            }
          }
        ]
      , [ "private-hdrs"
        , { "type": "to_subdir"
          , "subdir": {"type": "var", "name": "stage"}
          , "$1":
            { "type": "let*"
            , "bindings": [["fieldname", "private-hdrs"]]
            , "body": {"type": "CALL_EXPRESSION", "name": "artifacts"}
            }
          }
        ]
      , ["host-trans", {"type": "CALL_EXPRESSION", "name": "host transition"}]
      , ["defaults-transition", {"type": "var", "name": "host-trans"}]
      , ["deps-transition", {"type": "var", "name": "host-trans"}]
      , ["deps-fieldnames", ["private-deps", "defaults"]]
      , [ "runner"
        , { "type": "let*"
          , "bindings":
            [ ["fieldname", "runner"]
            , ["location", "runner"]
            , ["transition", {"type": "var", "name": "host-trans"}]
            ]
          , "body": {"type": "CALL_EXPRESSION", "name": "stage"}
          }
        ]
      , ["test-args", {"type": "FIELD", "name": "args", "default": []}]
      , [ "test-data"
        , { "type": "let*"
          , "bindings":
            [ ["fieldname", "data"]
            , ["transition", {"type": "var", "name": "deps-transition"}]
            ]
          , "body":
            { "type": "map_union"
            , "$1":
              [ {"type": "CALL_EXPRESSION", "name": "runfiles"}
              , {"type": "CALL_EXPRESSION", "name": "artifacts"}
              ]
            }
          }
        ]
      , [ "summarizer"
        , { "type": "let*"
          , "bindings":
            [["fieldname", "summarizer"], ["location", "summarizer"]]
          , "body": {"type": "CALL_EXPRESSION", "name": "stage"}
          }
        ]
      , [ "summary artifacts"
        , { "type": "++"
          , "$1":
            [ ["result"]
            , { "type": "let*"
              , "bindings":
                [["provider", "artifacts"], ["fieldname", "summarizer"]]
              , "body": {"type": "CALL_EXPRESSION", "name": "field_list"}
              }
            ]
          }
        ]
      ]
    , "body": {"type": "CALL_EXPRESSION", "name": "run_test"}
    }
  }
}