blob: 88555870aa1b50fb9646240b60dae48b764a2552 [file] [log] [blame]
/*
* Copyright 2018-present Facebook, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may
* not use this file except in compliance with the License. You may obtain
* a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*/
{namespace rust_common}
/***/
{template .supported_language_version}
Note: Buck is currently tested with (and therefore supports) version 1.32.0 of Rust.
{/template}
/***/
{template .check_flavor}
If you invoke a build with the <code>check</code> flavor, then Buck will invoke rustc
to check the code (typecheck, produce warnings, etc), but won't generate an executable code.
When applied to binaries it produces no output; for libraries it produces metadata for
consumers of the library. When building with <code>check</code>, extra compiler flags from
the <code>rust.rustc_check_flags</code> are added to the compiler's command line options,
to allow for extra warnings, etc.
{/template}
/***/
{template .deps_arg}
{call buck.arg}
{param name : 'deps' /}
{param default : '[]' /}
{param desc}
The set of dependencies of this rule. Currently, this supports rust_library
and prebuilt_rust_library rules.
{/param}
{/call}
{/template}
/***/
{template .srcs_arg}
{call buck.arg}
{param name : 'srcs' /}
{param desc}
<p>
The set of Rust source files to be compiled by this rule.
</p>
<p>
One of the source files is the root module of the crate. By default this is{sp}
<code>lib.rs</code> for libraries, <code>main.rs</code> for executables, or
the crate's name with <code>.rs</code> appended. This can be overridden with the{sp}
<code>crate_root</code> rule parameter.
</p>
{/param}
{/call}
{/template}
/***/
{template .features_arg}
{call buck.arg}
{param name : 'features' /}
{param default : '[]' /}
{param desc}
<p>
The set of features to be enabled for this rule.
</p>
<p>
These are passed to <code>rustc</code> with <code>--cfg feature="{lb}feature{rb}"</code>,{sp}
and can be used in the code with <code>#[cfg(feature = "{lb}feature{rb}")]</code>.
</p>
{/param}
{/call}
{/template}
/***/
{template .edition_arg}
{call buck.arg}
{param name : 'edition' /}
{param desc}
<p>
Set the language edition to be used for this rule. Can be set to any edition the
compiler supports (<code>2018</code> right now). If unset it uses the compiler's default
(<code>2015</code>).
</p>
{/param}
{/call}
{/template}
/***/
{template .rustc_flags_arg}
{call buck.arg}
{param name : 'rustc_flags' /}
{param default : '[]' /}
{param desc}
The set of additional compiler flags to pass to <code>rustc</code>.
{/param}
{/call}
{/template}
/***/
{template .linker_flags_arg}
{call buck.arg}
{param name : 'linker_flags' /}
{param default : '[]' /}
{param desc}
The set of additional flags to pass to the linker.
{/param}
{/call}
{/template}
/***/
{template .crate}
{call buck.arg}
{param name : 'crate' /}
{param default : 'rule name' /}
{param desc}
<p>
Set the generated crate name (for libraries) or executable name (for binaries), independent
of the rule name. Defaults to the rule name.
</p>
{/param}
{/call}
{/template}
/***/
{template .crate_root}
{call buck.arg}
{param name : 'crate_root' /}
{param default : 'derived from crate name' /}
{param desc}
<p>
Set the name of the top-level source file for the crate, which can be used to override the
default (see <code>srcs</code>).
</p>
{/param}
{/call}
{/template}
/***/
{template .env_arg}
{call buck.arg}
{param name : 'env' /}
{{param default : '{}' /}}
{param desc}
<p>
Set environment variables for this rule's invocations of rustc. The environment variable
values may include macros which are expanded.
</p>
{/param}
{/call}
{/template}
/***/
{template .mapped_srcs_arg}
{call buck.arg}
{param name : 'mapped_srcs' /}
{{param default : '{}' /}}
{param desc}
<p>
Add source files along with a local path mapping. Rust is sensitive to the layout of
source files, as the directory structure follows the module structure. However this is
awkward if the source file is, for example, generated by another rule. In this case, you
can set up a mapping from the actual source path to something that makes sense locally.
For example <code>mapped_srcs = {lb} ":generate-module", "src/generated.rs" {rb}</code>.
These are added to the regular <code>srcs</code>, so a file should not be listed in
both.
</p>
{/param}
{/call}
{/template}
/***/
{template .named_deps_arg}
{call buck.arg}
{param name : 'named_deps' /}
{{param default : '{}' /}}
{param desc}
<p>
Add crate dependencies and define a local name by which to use that dependency by. This
allows a crate to have multiple dependencies with the same crate name. For example:
<code>named_deps = {lb} "local_name", ":some_rust_crate" {rb}</code>.
The dependencies may also be non-Rust, but the alias is ignored. It has no effect on the
symbols provided by a C/C++ library.
</p>
{/param}
{/call}
{/template}
/***/
{template .more_examples}
<p>
For more examples, check out our <a
href="https://github.com/facebook/buck/tree/master/test/com/facebook/buck/rust/testdata/">
integration tests</a>.
</p>
{/template}