documentation/docs/Developer-Guide_Extensions-Hooks.md

# Extension Hooks

- This file is autogenerated by the armbian/build repository.

## Hooks

- Hooks are listed in the order they are called.
- Individual/specific hook functions can be [skipped/ignored/opted-out](/Developer-Guide_Extensions#opt-out-of-individual-hook-functions).

### `post_family_config`

> *give the config a chance to override the family/arch defaults*

This hook is called after the family configuration (`sources/families/xxx.conf`) is sourced. Since the family can
override values from the user configuration and the board configuration, it is often used to in turn override those.

Also known as (for backwards compatibility only):

- `config_tweaks_post_family_config`

### `user_config`

> *Invoke function with user override*

Allows for overriding configuration values set anywhere else. It is called after sourcing the `lib.config` file if it
exists, but before assembling any package lists.

### `extension_prepare_config`

> *allow extensions to prepare their own config, after user config is done*

Implementors should preserve variable values pre-set, but can default values an/or validate them. This runs *after*
user_config. Don't change anything not coming from other variables or meant to be configured by the user.

### `post_aggregate_packages`

> *For final user override, using a function, after all aggregations are done*

Called after aggregating all package lists, before the end of `compilation.sh`. Packages will still be installed after
this is called, so it is the last chance to confirm or change any packages.

Also known as (for backwards compatibility only):

- `user_config_post_aggregate_packages`

### `post_determine_cthreads`

> *give config a chance modify CTHREADS programatically. A build server may work better with hyperthreads-1 for example.*

Called early, before any compilation work starts.

Also known as (for backwards compatibility only):

- `config_post_determine_cthreads`

### `add_host_dependencies`

> *run before installing host dependencies*

you can add packages to install, space separated, to ${EXTRA_BUILD_DEPS} here.

### `fetch_sources_tools`

> *fetch host-side sources needed for tools and build*

Run early to fetch_from_repo or otherwise obtain sources for needed tools.

### `build_host_tools`

> *build needed tools for the build, host-side*

After sources are fetched, build host-side tools needed for the build.

### `pre_install_distribution_specific`

> *give config a chance to act before install_distribution_specific*

Called after `create_rootfs_cache` (_prepare basic rootfs: unpack cache or create from scratch_) but
before `install_distribution_specific` (_install distribution and board specific applications_).

Also known as (for backwards compatibility only):

- `config_pre_install_distribution_specific`

### `pre_install_kernel_debs`

> *called before installing the Armbian-built kernel deb packages*

It is not too late to `unset KERNELSOURCE` here and avoid kernel install.

### `post_install_kernel_debs`

> *allow config to do more with the installed kernel/headers*

Called after packages, u-boot, kernel and headers installed in the chroot, but before the BSP is installed.
If `KERNELSOURCE` is (still?) unset after this, Armbian-built firmware will not be installed.

### `post_family_tweaks`

> *customize the tweaks made by $LINUXFAMILY-specific family_tweaks*

It is run after packages are installed in the rootfs, but before enabling additional services. It allows implementors
access to the rootfs (`${SDCARD}`) in its pristine state after packages are installed.

### `pre_customize_image`

> *run before customize-image.sh*

This hook is called before `customize-image.sh` is executed and before the overlay is mounted. It thus can be used
for the same purposes as `customize-image.sh` without the overlay.

Also known as (for backwards compatibility only):

- `image_tweaks_pre_customize`

### `post_customize_image`

> *post customize-image.sh hook*

Run after the customize-image.sh script is run, and the overlay is unmounted.

Also known as (for backwards compatibility only):

- `image_tweaks_post_customize`

### `post_post_debootstrap_tweaks`

> *run after removing diversions and qemu with chroot unmounted*

Last chance to touch the `${SDCARD}` filesystem before it is copied to the final media. It is too late to run any
chrooted commands, since the supporting filesystems are already unmounted.

Also known as (for backwards compatibility only):

- `config_post_debootstrap_tweaks`

### `pre_prepare_partitions`

> *allow custom options for mkfs*

Good time to change stuff like mkfs opts, types etc.

Also known as (for backwards compatibility only):

- `prepare_partitions_custom`

### `prepare_image_size`

> *allow dynamically determining the size based on the $rootfs_size*

Called after `${rootfs_size}` is known, but before `${FIXED_IMAGE_SIZE}` is taken into account. A good spot to
determine `FIXED_IMAGE_SIZE` based on `rootfs_size`. UEFISIZE can be set to 0 for no UEFI partition, or to a size in MiB
to include one. Last chance to set `USE_HOOK_FOR_PARTITION`=yes and then implement create_partition_table hook_point.

Also known as (for backwards compatibility only):

- `config_prepare_image_size`

### `post_create_partitions`

> *called after all partitions are created, but not yet formatted*

### `format_partitions`

> *if you created your own partitions, this would be a good time to format them*

The loop device is mounted, so ${LOOP}p1 is it's first partition etc.

### `pre_update_initramfs`

> *allow config to hack into the initramfs create process*

Called after rsync has synced both `/root` and `/root` on the target, but before calling `update_initramfs`.

Also known as (for backwards compatibility only):

- `config_pre_update_initramfs`

### `pre_umount_final_image`

> *allow config to hack into the image before the unmount*

Called before unmounting both `/root` and `/boot`.

Also known as (for backwards compatibility only):

- `config_pre_umount_final_image`

### `post_umount_final_image`

> *allow config to hack into the image after the unmount*

Called after unmounting both `/root` and `/boot`.

Also known as (for backwards compatibility only):

- `config_post_umount_final_image`

### `post_build_image`

> *custom post build hook*

Called after the final .img file is built, before it is (possibly) written to an SD writer.

- *NOTE*: this hook used to take an argument ($1) for the final image produced.
    - Now it is passed as an environment variable `${FINAL_IMAGE_FILE}`
      It is the last possible chance to modify `$CARD_DEVICE`.

### `run_after_build`

> *hook for function to run after build, i.e. to change owner of `$SRC`*

Really one of the last hooks ever called. The build has ended. Congratulations.

- *NOTE:* this will run only if there were no errors during build process.

### `extension_metadata_ready`

> *meta-Meta time!*

Implement this hook to work with/on the meta-data made available by the extension manager. Interesting stuff to process:

- `"${EXTENSION_MANAGER_TMP_DIR}/hook_point_calls.txt"` contains a list of all hook points called, in order.
- For each hook_point in the list, more files will have metadata about that hook point.
    - `${EXTENSION_MANAGER_TMP_DIR}/hook_point.orig.md` contains the hook documentation at the call site (inline docs),
      hopefully in Markdown format.
    - `${EXTENSION_MANAGER_TMP_DIR}/hook_point.compat` contains the compatibility names for the hooks.
    - `${EXTENSION_MANAGER_TMP_DIR}/hook_point.exports` contains _exported_ environment variables.
    - `${EXTENSION_MANAGER_TMP_DIR}/hook_point.vars` contains _all_ environment variables.
- `${defined_hook_point_functions}` is a map of _all_ the defined hook point functions and their extension information.
- `${hook_point_function_trace_sources}` is a map of all the hook point functions _that were really called during the
  build_ and their BASH_SOURCE information.
- `${hook_point_function_trace_lines}` is the same, but BASH_LINENO info. After this hook is done,
  the `${EXTENSION_MANAGER_TMP_DIR}` will be removed.