From 56d66ff8b8616b6ec07c2c604da5d717c0a91aff Mon Sep 17 00:00:00 2001 From: John Cater Date: Thu, 23 Feb 2017 17:55:22 +0000 Subject: Remove duplicate genrule documentation on base class. -- Change-Id: Ie33953add6a582368b6b0da74c478a8dd301acb4 Reviewed-on: https://cr.bazel.build/9041 PiperOrigin-RevId: 148355280 MOS_MIGRATED_REVID=148355280 --- .../build/lib/rules/genrule/GenRuleBaseRule.java | 148 --------------------- 1 file changed, 148 deletions(-) (limited to 'src') diff --git a/src/main/java/com/google/devtools/build/lib/rules/genrule/GenRuleBaseRule.java b/src/main/java/com/google/devtools/build/lib/rules/genrule/GenRuleBaseRule.java index 36ee679de5..530f51b1ee 100644 --- a/src/main/java/com/google/devtools/build/lib/rules/genrule/GenRuleBaseRule.java +++ b/src/main/java/com/google/devtools/build/lib/rules/genrule/GenRuleBaseRule.java @@ -237,151 +237,3 @@ public class GenRuleBaseRule implements RuleDefinition { .build(); } } - -/* - -

A genrule generates one or more files using a user-defined Bash command.

- -

- Genrules are generic build rules that you can use if there's no specific rule for the task. If for - example you want to minify JavaScript files then you can use a genrule to do so. If however you - need to compile C++ files, stick to the existing cc_* rules, because all the heavy - lifting has already been done for you. -

-

- Do not use a genrule for running tests. There are special dispensations for tests and test - results, including caching policies and environment variables. Tests generally need to be run - after the build is complete and on the target architecture, whereas genrules are executed during - the build and on the host architecture (the two may be different). If you need a general purpose - testing rule, use sh_test. -

- -

Cross-compilation Considerations

- -

- See the user manual for more info about - cross-compilation. -

-

- While genrules run during a build, their outputs are often used after the build, for deployment or - testing. Consider the example of compiling C code for a microcontroller: the compiler accepts C - source files and generates code that runs on a microcontroller. The generated code obviously - cannot run on the CPU that was used for building it, but the C compiler (if compiled from source) - itself has to. -

-

- The build system uses the host configuration to describe the machine(s) on which the build runs - and the target configuration to describe the machine(s) on which the output of the build is - supposed to run. It provides options to configure each of these and it segregates the - corresponding files into separate directories to avoid conflicts. -

-

- For genrules, the build system ensures that dependencies are built appropriately: - srcs are built (if necessary) for the target configuration, - tools are built for the host configuration, and the output is considered to - be for the target configuration. It also provides - "Make" variables that genrule commands can pass to the corresponding tools. -

-

- It is intentional that genrule defines no deps attribute: other built-in rules use - language-dependent meta information passed between the rules to automatically determine how to - handle dependent rules, but this level of automation is not possible for genrules. Genrules work - purely at the file and runfiles level. -

- -

Special Cases

- -

- Host-host compilation: in some cases, the build system needs to run genrules such that the - output can also be executed during the build. If for example a genrule builds some custom compiler - which is subsequently used by another genrule, the first one has to produce its output for the - host configuration, because that's where the compiler will run in the other genrule. In this case, - the build system does the right thing automatically: it builds the srcs and - outs of the first genrule for the host configuration instead of the target - configuration. See the user manual for more - info. -

-

- JDK & C++ Tooling: to use a tool from the JDK or the C++ compiler suite, the build system - provides a set of variables to use. See "Make" variable for - details. -

- -

Genrule Environment

- -

- The genrule command is executed in a Bash shell, configured to fail when a command or a pipeline - fails (set -e -o pipefail). Genrules should not access the network (except to create - connections between processes running within the same genrule on the same machine), though this is - not currently enforced. -

-

- The build system automatically deletes any existing output files, but creates any necessary parent - directories before it runs a genrule. It also removes any output files in case of a failure. -

- -

General Advice

- - - -

Examples

- -

- This example generates foo.h. There are no sources, because the command doesn't take - any input. The "binary" run by the command is a perl script in the same package as the genrule. -

-
-genrule(
-    name = "foo",
-    srcs = [],
-    outs = ["foo.h"],
-    cmd = "./$(location create_foo.pl) > \"$@\"",
-    tools = ["create_foo.pl"],
-)
-
- -

- The following example shows how to use a filegroup - and the outputs of another genrule. Note that using $(SRCS) instead - of explicit $(location) directives would also work; this example uses the latter for - sake of demonstration. -

-
-genrule(
-    name = "concat_all_files",
-    srcs = [
-        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
-        "//other:gen",   # a genrule with a single output ==> $(location)
-    ],
-    outs = ["concatenated.txt"],
-    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
-)
-
- -*/ -- cgit v1.2.3