apk_genrule

An apk_genrule() rule is used to post-process an APK. What separates an apk_genrule from a genrule is apk_genrules are known by BUCK to produce APKs, so commands like buck install or buck uninstall still work. Additionally, apk_genrule() rules can be inputs to other apk_genrule() rules.

Function Signature

def apk_genrule(
    *,
    name: str,
    default_target_platform: None | str = None,
    target_compatible_with: list[str] = [],
    compatible_with: list[str] = [],
    exec_compatible_with: list[str] = [],
    visibility: list[str] = [],
    within_view: list[str] = ["PUBLIC"],
    metadata: OpaqueMetadata = {},
    tests: list[str] = [],
    modifiers: OpaqueMetadata = [],
    _android_toolchain: str = "gh_facebook_buck2_shims_meta//:android",
    _apple_platforms: dict[str, str] = {},
    _build_only_native_code: bool = select({"prelude//android/constraints:build_only_native_code": True, "DEFAULT": False}),
    _exec_os_type: str = "prelude//os_lookup/targets:os_lookup",
    _genrule_toolchain: str = "gh_facebook_buck2_shims_meta//:genrule",
    _java_toolchain: str = "gh_facebook_buck2_shims_meta//:java_for_android",
    aab: None | str = None,
    always_print_stderr: bool = False,
    apk: None | str = None,
    bash: None | str = None,
    cacheable: None | bool = None,
    cmd: None | str = None,
    cmd_exe: None | str = None,
    contacts: list[str] = [],
    default_host_platform: None | str = None,
    default_outs: None | list[str] = None,
    enable_sandbox: None | bool = None,
    environment_expansion_separator: None | str = None,
    is_cacheable: bool = False,
    keystore: None | str = None,
    labels: list[str] = [],
    licenses: list[str] = [],
    metadata_env_var: None | str = None,
    metadata_path: None | str = None,
    need_android_tools: bool = False,
    no_outputs_cleanup: bool = False,
    out: None | str = None,
    outs: None | dict[str, list[str]] = None,
    remote: None | bool = None,
    remote_execution_dependencies: list[dict[str, str]] = [],
    srcs: list[str] | dict[str, str] = [],
    type: str = "apk",
    use_derived_apk: bool = False,
    weight: None | int = None,
) -> None

Parameters

• name: (required)

  name of the target

• default_target_platform: (defaults to: None)

  specifies the default target platform, used when no platforms are specified on the command line

• target_compatible_with: (defaults to: [])

  a list of constraints that are required to be satisfied for this target to be compatible with a configuration

• compatible_with: (defaults to: [])

  a list of constraints that are required to be satisfied for this target to be compatible with a configuration

• exec_compatible_with: (defaults to: [])

  a list of constraints that are required to be satisfied for this target to be compatible with an execution platform

• visibility: (defaults to: [])

  a list of visibility patterns restricting what targets can depend on this one

• within_view: (defaults to: ["PUBLIC"])

  a list of visibility patterns restricting what this target can depend on

• metadata: (defaults to: {})

  a key-value map of metadata associated with this target

• tests: (defaults to: [])

  a list of targets that provide tests for this one

• modifiers: (defaults to: [])

  an array of modifiers associated with this target

• aab: (defaults to: None)

  The input android_binary() rule. The path to the AAB can be accessed with the $AAB shell variable. Only one of apk or aab can be provided.

• apk: (defaults to: None)

  The input android_binary() rule. The path to the APK can be accessed with the $APK shell variable. Only one of apk or aab can be provided.

• bash: (defaults to: None)

  A platform-specific version of the shell command parameter cmd. It runs on Linux and UNIX systems—including OSX—on which bash is installed. It has a higher priority than cmd. The bash argument is run with /usr/bin/env bash -c. It has access to the same set of macros and variables as the cmd argument.

• cmd: (defaults to: None)

  The shell command to run to generate the output file. It is the fallback for bash and cmd_exe arguments. The following environment variables are populated by Buck and available to the shell command. They are accessed using the syntax:

  ${<variable>}

  Example:

  ${SRCS}

  ${SRCS}

  A string expansion of the srcs argument delimited by the environment_expansion_separator argument where each element of srcs will be translated into a relative path.

  ${SRCDIR}

  The relative path to a directory to which sources are copied prior to running the command.

  ${OUT}

  The output file or directory for the genrule(). This variable will have whatever value is specified by the out argument if not using named outputs. If using named outputs, this variable will be the output directory.

  The value should be a valid filepath. The semantics of the shell command determine whether this filepath is treated as a file or a directory. If the filepath is a directory, then the shell command needs to create it if not using named outputs. Otherwise, it will be automatically created. All outputs (directories and files) must be readable, writable, and (in the case of directories) executable by the current user.

  The file or directory specified by this variable must always be written by this command. If not, the execution of this rule will be considered a failure, halting the build process.

  ${TMP}

  A temporary directory which can be used for intermediate results and will not be bundled into the output.

• cmd_exe: (defaults to: None)

  A platform-specific version of the shell command parameter cmd. It runs on Windows and has a higher priority than cmd. The cmd_exe argument is run with cmd.exe /v:off /c. It has access to the same set of macros and variables as the cmd argument.

• environment_expansion_separator: (defaults to: None)

  The delimiter between paths in environment variables, such as SRCS, that can contain multiple paths. It can be useful to specify this parameter if the paths could contain spaces.

• out: (defaults to: None)

  The name of the output file or directory. The complete path to this argument is provided to the shell command through the OUT environment variable. Only one of out or outs may be present.

  For an apk_genrule the output should be a '.apk' or '.aab' file.

• srcs: (defaults to: [])

  Either a list or a map of the source files which Buck makes available to the shell command at the path in the SRCDIR environment variable. If you specify a list, the source files are the names in the list. If you specify a map, the source files are made available as the names in the keys of the map, where the values of the map are the original source file names.

• weight: (defaults to: None)

  How many local slots these genrule should take when executing locally.

Examples

Here is an example of a couple apk_genrule() open up an APK, do some super signing, and then zipalign that APK again.

# Building this rule will produce a file named messenger.apk.
android_binary(
  name = 'messenger',
  manifest = 'AndroidManifest.xml',
  target = 'Google Inc.:Google APIs:16',
  keystore = '//keystores:prod',
  package_type = 'release',
  proguard_config = 'proguard.cfg',
  deps = [
    ':res',
    ':src',
  ],
)

apk_genrule(
  name = 'messenger_super_sign_unalign',
  apk = ':messenger',
  bash = '$(exe //java/com/facebook/sign:super_sign) --input $APK --output $OUT',
  cmd_exe = '$(exe //java/com/facebook/sign:super_sign) --input %APK% --output %OUT%',
  out = 'messenger_super_sign_unalign.apk',
)

apk_genrule(
  name = 'messenger_super_sign',
  apk = ':messenger_super_sign_unalign',
  bash = '$ANDROID_HOME/tools/zipalign -f 4 $APK $OUT',
  cmd_exe = '%ANDROID_HOME%\tools\zipalign -f 4 %APK% %OUT%',
  out = 'messenger_super_sign.apk',
)