Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: reformat bob_alias docs #669

Merged
merged 1 commit into from
Oct 6, 2023
Merged

docs: reformat bob_alias docs #669

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,22 +12,30 @@

## Reference info

- [Common module properties](module_types/common_module_properties.md)
- [Common generate module properties](module_types/common_generate_module_properties.md)
### Legacy Modules

> Legacy modules will not be supported by the [Gazelle plugin](../../gazelle/README.md).

- [bob_alias](module_types/bob_alias.md)
- [bob_binary](module_types/bob_binary.md)
- [bob_defaults](module_types/bob_defaults.md)
- [bob_external_header_library](module_types/bob_external_library.md)
- [bob_external_shared_library](module_types/bob_external_library.md)
- [bob_external_static_library](module_types/bob_external_library.md)
- [bob_generate_binary](module_types/bob_generate_library.md)
- [bob_generate_shared_library](module_types/bob_generate_library.md)
- [bob_external_header_library](module_types/bob_external_header_library.md)
- [bob_external_shared_library](module_types/bob_external_shared_library.md)
- [bob_external_static_library](module_types/bob_external_static_library.md)
- [bob_generate_binary](module_types/bob_generate_binary.md)
- [bob_generate_shared_library](module_types/bob_generate_shared_library.md)
- [bob_generate_source](module_types/bob_generate_source.md)
- [bob_generate_static_library](module_types/bob_generate_library.md)
- [bob_generate_static_library](module_types/bob_generate_static_library.md)
- [bob_install_group](module_types/bob_install_group.md)
- [bob_kernel_module](module_types/bob_kernel_module.md)
- [bob_resource](module_types/bob_resource.md)
- [bob_shared_library](module_types/bob_shared_library.md)
- [bob_static_library](module_types/bob_static_library.md)
- [bob_transform_source](module_types/bob_transform_source.md)

### Strict Modules

- [bob_glob](module_types/bob_glob.md)
- [bob_filegroup](module_types/bob_filegroup.md)
- [bob_genrule](module_types/bob_genrule.md)
- [bob_gensrcs](module_types/bob_gensrcs.md)
48 changes: 17 additions & 31 deletions docs/module_types/bob_alias.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,12 @@
# Module: bob_alias
# `bob_alias`

> This is a legacy target will not be supported by the [Gazelle plugin](../../gazelle/README.md).

```bp
bob_alias {
name, srcs, add_to_alias,
}
```

This target is used to trigger builds of multiple other targets.
This target itself does not build anything, it just ensures all
Expand All @@ -12,36 +20,14 @@ An alias will not try to build a target that is disabled. This
simplifies the use of aliases, so you don't have to try and
replicate the enable conditions on the target to avoid errors.

`bob_alias` supports [features](../features.md)

## Full specification of `bob_alias` properties

```bp
bob_alias {
name: "custom_name",
srcs: ["module_name_foo", "module_name_bar"],

add_to_alias: ["bob_alias_module_name"],

// features available
}
```

---

### **bob_alias.name** (required)

The unique identifier that can be used to refer to this module.

---

### **bob_alias.srcs** (optional)

Modules that this alias will cause to build.
Supports:

---
- [features](../features.md)

### **bob_alias.add_to_alias** (optional)
## Properties

Allows this alias to add itself to another alias.
`bob_alias_module_name` should refer to existing `bob_alias`.
| | |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [`name`](properties/common_properties.md#name) | String; required |
| `srcs` | List of targets; default is `[]`<br>Modules that this alias will cause to build. |
| `add_to_alias` | Target; default is `none`<br>Allows this alias to add itself to another alias.<br>Should refer to existing `bob_alias`. |
119 changes: 53 additions & 66 deletions docs/module_types/bob_binary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,72 +1,59 @@
# Module: bob_binary
# `bob_binary`

Target is an executable.

## Full specification of `bob_binary` properties

Most properties are optional.

`bob_binary` supports [features](../features.md)

For general common properties please [check detailed documentation](common_module_properties.md).
> This is a legacy target and will not be supported by the [Gazelle plugin](../../gazelle/README.md)

```bp
bob_binary {
name: "custom_name",
srcs: ["src/a.cpp", "src/b.cpp", "src/common/*.cpp"],
exclude_srcs: ["src/common/skip_this.cpp"],

enabled: false,
build_by_default: true,

add_to_alias: ["bob_alias.name"],

defaults: ["bob_default.name"],

target_supported: true,
target: { ... },

host_supported: true,
host: { ... },

out: "alternate_output_name",

cflags: ["-DDEBUG=1", "-Wall"],
cxxflags: ["..."],
asflags: ["..."],
conlyflags: ["..."],

ldflags: ["..."],
ldlibs: ["-lz"],

static_libs: ["bob_static_lib.name", "bob_generated_static.name"],
shared_libs: ["bob_shared_lib.name", "bob_generated_shared.name"],

generated_headers: ["module_name"],
generated_sources: ["module_name"],
generated_deps: ["module_name"],

tags: ["optional"],
owner: "company_name",
strip: true,

include_dirs: ["include/"],
local_include_dirs: ["include/"],

build_wrapper: "ccache",

add_lib_dirs_to_rpath: true,

install_group: "bob_install_group.name",
install_deps: ["module_name"],
relative_install_path: "unit/objects",
debug_info: "bob_install_group.name",
post_install_tool: "post_install.py",
post_install_cmd: "${tool} ${args} ${out}",
post_install_args: ["arg1", "arg2"],

version_script: "exports.map",

// features available
name, srcs, exclude_srcs, enabled, build_by_default, add_to_alias, defaults, target_supported, target, host_supported, host, out, cflags, cxxflags, asflags, conlyflags, ldflags, ldlibs, static_libs, shared_libs, generated_headers, generated_sources, generated_deps, tags, owner, strip, include_dirs, local_include_dirs, build_wrapper, add_lib_dirs_to_rpath, install_group, install_deps, relative_install_path, debug_info, post_install_tool, post_install_cmd, post_install_args, version_script
}
```

Target is an executable.

Supports:

- [features](../features.md)
- [defaults](./bob_defaults.md)

## Properties

| | |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`name`](properties/common_properties.md#name) | String; required |
| [`srcs`](properties/common_properties.md#srcs) | List of sources; default is `[]` |
| `exclude_srcs` | List of exclude patterns; default is `[]`<br> Files to be removed from `srcs`.<br>Supports wildcards, with the same caveat as `srcs`. |
| [`enabled`](properties/common_properties.md#enabled) | Boolean; default is `true`. |
| `build_by_default` | Boolean; default is `true`<br>Whether it is built by default in a build with no targets requested. |
| `add_to_alias` | Target; default is `none`<br>Allows this alias to add itself to another alias.<br>Should refer to existing `bob_alias`. |
| [`defaults`](properties/legacy_properties.md#defaults) | List of [`bob_defaults`](bob_defaults.md); default is `[]` |
| [`target_supported`](properties/common_properties.md#target_supported) | Boolean; default is `true`. |
| [`target`](properties/common_properties.md#target) | Property map; default is `{}`. |
| [`host_supported`](<(properties/common_properties.md#host_supported)>) | Boolean; default is `false`. |
| [`host`](<(properties/common_properties.md#host)>) | Property map; default is `{}`. |
| `out` | String;<br>Alternate output name, used for the file name and Android rules. |
| [`cflags`](properties/legacy_properties.md#cflags) | List of strings; default is `[]`<br>Flags used for C/C++ compilation. |
| `conlyflags` | List of strings; default is `[]`<br>Flags used for C compilation.<br>See [`cflags`](properties/legacy_properties.md#cflags) |
| `cxxflags` | List of strings; default is `[]`<br>Flags used for C++ compilation.<br>See [`cflags`](properties/legacy_properties.md#cflags) |
| [`asflags`](properties/legacy_properties.md#asflags) | List of strings; default is `[]`<br>Flags used for assembly compilation. |
| [`ldflags`](properties/legacy_properties.md#ldflags) | List of strings; default is `[]`<br>Flags used for linking. |
| [`ldlibs`](properties/legacy_properties.md#ldlibs) | List of strings; default is `[]`<br>Linker flags required to link to the necessary system libraries. |
| [`static_libs`](properties/legacy_properties.md#static_libs) | List of targets; default is `[]`<br>The list of static lib modules that this library depends on. |
| [`shared_libs`](properties/legacy_properties.md#shared_libs) | List of targets; default is `[]`<br> |
| [`generated_headers`](properties/legacy_properties.md#generated_headers) | List of targets; default is `[]`<br> |
| [`generated_sources`](properties/legacy_properties.md#generated_sources) | List of targets; default is `[]`<br> |
| [`generated_deps`](properties/legacy_properties.md#generated_deps) | List of targets; default is `[]`<br> |
| [`owner`](properties/legacy_properties.md#owner) | String; default is `none`; **deprecated**<br> If set, then the module is considered proprietary. |
| [`strip`](properties/legacy_properties.md#strip) | Boolean; default is `false`.<br> When set, strip symbols and debug information from libraries and binaries. |
| [`include_dirs`](properties/legacy_properties.md#include_dirs) | List of strings; default is `[]`<br>A list of include directories to use. These are expected to be system headers, and will usually be an absolute path. |
| [`local_include_dirs`](properties/legacy_properties.md#local_include_dirs) | List of strings; default is `[]`<br>A list of include directories to use. These are relative to the `build.bp` containing the module definition |
| [`build_wrapper`](properties/legacy_properties.md#build_wrapper) | String; default is `none`.<br>Wrapper for all build commands. |
| [`add_lib_dirs_to_rpath`](properties/legacy_properties.md#add_lib_dirs_to_rpath) | Boolean; default is `false`<br>If true, the module's shared libraries' directories will be added to its DT_RUNPATH entry. |
| [`install_group`](properties/legacy_properties.md#install_group) | Target; default is `none`<br>Module name of a `bob_install_group` specifying an installation directory. |
| [`install_deps`](properties/legacy_properties.md#install_deps) | List of targets; default is `[]`<br>Other modules which must be installed. |
| `relative_install_path` | String; default is `none`<br>Path to install to, relative to the install_group's path. |
| [`debug_info`](properties/legacy_properties.md#debug_info) | Target; default is `none`<br>Module name of a `bob_install_group` specifying an installation directory for debug information. |
| `post_install_tool` | String <br>Script used during post install. Not supported on Android. |
| [`post_install_cmd`](properties/legacy_properties.md#post_install_cmd) | String; default is `none`<br>Command to execute on file(s) after they are installed. |
| [`post_install_args`](properties/legacy_properties.md#post_install_args) | List of strings; default is `[]`<br>Arguments to insert into `post_install_cmd`. |
| `version_script` | Linker script used for [symbol versioning](../user_guide/libraries_2.md#markdown-header-symbol-versioning). |
| [`tags`](properties/common_properties.md#tags) | List of strings; default is `[]` |
103 changes: 14 additions & 89 deletions docs/module_types/bob_defaults.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,102 +1,25 @@
# Module: bob_defaults

Defaults are used to share common settings between multiple modules.

`bob_defaults` can be used by `bob_static_lib`, `bob_shared_lib`, `bob_binary`,
and `bob_kernel_module`.

## Full specification of `bob_defaults` properties

Most properties are optional.

`bob_defaults` supports [features](../features.md)

For detailed documentation please go to [common module properties](common_module_properties.md).
For kernel module related stuff please check [bob_kernel_module](bob_kernel_module.md)
# bob_defaults

```bp
bob_defaults {
name: "custom_name",
srcs: ["src/a.cpp", "src/b.cpp", "src/common/*.cpp"],
exclude_srcs: ["src/common/skip_this.cpp"],

enabled: false,
build_by_default: true,

add_to_alias: ["bob_alias.name"],

defaults: ["bob_default.name"],

target_supported: true,
target: { ... },

host_supported: true,
host: { ... },

out: "alternate_output_name",

cflags: ["-DDEBUG=1", "-Wall"],
export_cflags: ["..."],

cxxflags: ["..."],
asflags: ["..."],
conlyflags: ["..."],

ldflags: ["..."],
export_ldflags: ["..."],

static_libs: ["bob_static_lib.name", "..."],

shared_libs: ["bob_shared_lib.name", "..."],

reexport_libs: ["bob_shared_lib.name", "bob_static_lib.name"],

whole_static_libs: ["bob_shared_lib.name", "bob_static_lib.name"],

ldlibs: ["-lz", "..."],

generated_headers: ["bob_generate_source.name"],
generated_sources: ["bob_transform_source.name"],
generated_deps: ["bob_generate_source.name"],

tags: ["optional"],
owner: "my_company",
strip: true,
name, srcs, exclude_srcs, enabled, build_by_default, add_to_alias, defaults, target_supported, target, host_supported, host, out, cflags, export_cflags, cxxflags, asflags, conlyflags, ldflags, export_ldflags, static_libs, shared_libs, reexport_libs, whole_static_libs, ldlibs, generated_headers, generated_sources, generated_deps, tags, owner, strip, include_dirs, local_include_dirs, export_local_include_dirs, export_include_dirs, build_wrapper, forwarding_shlib, kbuild_options, extra_symbols, make_args, kernel_dir, kernel_cross_compile, kernel_cc, kernel_hostcc, kernel_clang_triple, install_group, install_deps, relative_install_path, debug_info, post_install_tool, post_install_cmd, post_install_args, tags
}
```

include_dirs: ["include/"],
local_include_dirs: ["include/"],
export_local_include_dirs: ["include/"],
export_include_dirs: ["include/"],
Defaults are used to share common settings between modules.

build_wrapper: "ccache",
forwarding_shlib: true,
Supports:

// kernel module related stuff
kbuild_options: ["CONFIG_MY_OPTION=y"],
extra_symbols: ["bob_kernel_module.name"],
make_args: ["--ignore-errors"],
kernel_dir: "/kernel/linux/",
kernel_cross_compile: "prefix",
kernel_cc: "target",
kernel_hostcc: "host",
kernel_clang_triple: "triple",
// ^^ kernel module building related stuff
- [features](../features.md)
- [defaults](./bob_defaults.md) (recursive defaults are supported)

install_group: "bob_install_group.name",
install_deps: ["bob_resource.name"],
relative_install_path: "unit/objects",
debug_info: "bob_install_group.name",
post_install_tool: "post_install.py",
post_install_cmd: "${tool} ${args} ${out}",
post_install_args: ["arg1", "arg2"],
## Attributes

// features available
}
```
`bob_defaults` supports the same attributes as its consuming module. Refer to each module for detailed attribute documentation.

---
## Examples

# Examples
### Simple

Here, the `-lncurses` flag is used with linking the `less` binary,
because it has been propagated through the default.
Expand All @@ -114,6 +37,8 @@ bob_binary {
}
```

### Nested Defaults

Defaults can be hierarchical by including other defaults. Here, the
`my_unit_test` binary will inherit both the `-Wall` and `-UNDEBUG` flags.

Expand Down
Loading