blob: b8431fb99df814f98d6a585c7d45065e7bf837fc [file] [log] [blame]
/*
* Copyright (c) Facebook, Inc. and its affiliates.
*
* 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 cxx_library}
/***/
{template .soyweb}
{call buck.page}
{param title: 'cxx_library()' /}
{param navid: 'rule_cxx_library' /}
{param prettify: true /}
{param description}
A cxx_library() rule represents a set of C/C++ source files.
{/param}
{param content}
{call buck.rule}
{param status: 'UNFROZEN' /}
{param overview}
<p>
A <code>cxx_library()</code> rule specifies a set of C/C++ source files
and also provides flags that specify how those files should be built.
</p>
<h3>Building requires a specified top-level target</h3>
<p>
Whether a Buck command builds the <code>cxx_library</code> is
determined by the inclusion of a top-level target, such as
a {call buck.cxx_binary /} or {call buck.android_binary /}, that
transitively depends on the <code>cxx_library</code>. The set of
targets specified to the Buck command (<code>buck build</code>, <code>buck run</code>, etc) must
include one of these top-level targets in order for Buck to build
the <code>cxx_library</code>. Note that you could specify the top-level target
implicitly using a {call buck.build_target_pattern /} or you could also specify
the top-level target using an {call buckconfig.alias /} defined in <code>.buckconfig</code>.
</p>
<p>
<em>How</em> Buck builds the library also depends on the specified top-level target.
For example, a C/C++ binary (<code>cxx_binary</code>) would require a static non-PIC build of the library,
whereas an Android APK (<code>android_binary</code>) would require a shared PIC-enabled build.
(PIC stands for position-independent code.)
</p>
<h4>Dependencies of the cxx_library also require a top-level target</h4>
<p>
Similarly, in order for Buck to build a target that
the <code>cxx_library</code> depends on, such as a {call buck.cxx_genrule /},
you must specify in the Buck command a top-level target that depends on
the <code>cxx_library</code>. For example, you could specify
to {call buck.cmd_build /} a <code>cxx_binary</code> that
depends on the <code>cxx_library</code>. If you specify as
your build target the <code>cxx_library</code> itself, the build targets
that the <code>cxx_library</code> depends on <em>might not be built</em>.
</p>
{/param}
{param args}
{call buck.name_arg /}
{call cxx_common.srcs_arg /}
{call cxx_common.platform_srcs_arg /}
{call cxx_common.headers_arg /}
{call cxx_common.platform_headers_arg /}
{call cxx_common.exported_headers_arg /}
{call cxx_common.exported_header_style_arg /}
{call cxx_common.exported_platform_headers_arg /}
{call cxx_common.header_namespace_arg /}
{call cxx_common.preprocessor_flags_arg /}
{call cxx_common.lang_preprocessor_flags_arg /}
{call cxx_common.platform_preprocessor_flags_arg /}
{call cxx_common.lang_platform_preprocessor_flags_arg /}
{call cxx_common.exported_preprocessor_flags_arg /}
{call cxx_common.exported_lang_preprocessor_flags_arg /}
{call cxx_common.exported_platform_preprocessor_flags_arg /}
{call cxx_common.exported_lang_platform_preprocessor_flags_arg /}
{call cxx_common.compiler_flags_arg /}
{call cxx_common.lang_compiler_flags_arg /}
{call cxx_common.platform_compiler_flags_arg /}
{call cxx_common.lang_platform_compiler_flags_arg /}
{call cxx_common.linker_extra_outputs_arg /}
{call cxx_common.linker_flags_arg /}
{call cxx_common.platform_linker_flags_arg /}
{call cxx_common.exported_linker_flags_arg /}
{call cxx_common.exported_post_linker_flags_arg /}
{call cxx_common.exported_platform_linker_flags_arg /}
{call cxx_common.exported_post_platform_linker_flags_arg /}
{call native_common.link_style /}
{call native_common.link_whole /}
{call cxx_common.raw_headers_arg /}
{call cxx_common.include_directories_arg /}
{call cxx_common.public_include_directories_arg /}
{call cxx_common.public_system_include_directories_arg /}
{call buck.arg}
{param name : 'soname' /}
{param default : 'None' /}
{param desc}
Sets the soname ("shared object name") of any shared library produced from this rule.
The default value is based on the full rule name.
The macro <code>$(ext)</code> will be replaced with a platform-appropriate extension.
An argument can be provided, which is a library version.
For example <code>soname = 'libfoo.$(ext 2.3)'</code> will be{sp}
<code>libfoo.2.3.dylib</code> on Mac and <code>libfoo.so.2.3</code> on Linux.
{/param}
{/call}
{call cxx_common.supported_platforms_regex_arg /}
{call cxx_common.force_static /}
{call native_common.preferred_linkage /}
{call cxx_common.reexport_all_header_dependencies_arg /}
{call cxx_common.exported_deps_arg /}
{call cxx_common.exported_platform_deps_arg /}
{call cxx_common.precompiled_header_arg /}
{call buck.tests_arg /}
{call apple_common.extra_xcode_sources /}
{call apple_common.extra_xcode_files /}
{/param} // close args
{param examples}
{literal}<pre class="prettyprint lang-py">
# A rule that includes a single .cpp file and its corresponding header and
# also supplies an additional flag for compilation.
cxx_library(
name = 'fileutil',
srcs = [
'fileutil.cpp',
],
exported_headers = [
'fileutil.h',
],
compiler_flags = [
'-fno-omit-frame-pointer',
],
)
# A rule that defines explicit names for its headers
cxx_library(
name = 'mathutils',
header_namespace = 'math',
srcs = [
'trig/src/cos.cpp',
'trig/src/tan.cpp',
],
exported_headers = {
# These are included as &lt;math/trig/cos.h&gt; and &lt;math/trig/tan.h&gt;
'trig/cos.h': 'trig/include/cos.h',
'trig/tan.h': 'trig/include/tan.h',
},
compiler_flags = [
'-fno-omit-frame-pointer',
],
)
# A rule that uses different headers and sources per platform
cxx_library(
name = 'vector',
# Because of platform_headers, this file can include "config.h"
# and get the architecture specific header
srcs = ['vector.cpp'],
platform_srcs = [
('.*armv7$', 'armv7.S'),
('.*x86_64$', 'x86_64.S'),
],
exported_headers = [
'vector.h',
],
platform_headers = [
(
'.*armv7$',
{
'config.h': 'config-armv7.h',
}
),
(
'.*x86_64$',
{
'config.h': 'config-x86_64.h',
}
),
],
)
</pre>{/literal}
{/param}
{/call} // close buck.rule
{/param}
{/call}
{/template}