Package Build Flags

PKG_BUILD_FLAGS values that control compiler and linker behavior for individual OpenWrt packages.

PKG_BUILD_FLAGS is a space-separated list of flags set in a package’s Makefile to enable or disable specific compiler/linker optimizations and features. The flags are processed by include/package.mk.

Usage

# In your package Makefile:
PKG_BUILD_FLAGS:=gc-sections lto

Multiple flags can be combined:

PKG_BUILD_FLAGS:=gc-sections lto no-mips16

Available Flags

no-iremap — Disable source path remapping

Default behavior: Source path remapping is enabled by default (the iremap flag defaults to 1).

Path remapping rewrites the source directory path embedded in debug information to a short, reproducible path, which is required for reproducible builds.

PKG_BUILD_FLAGS:=no-iremap

When set, the -ffile-prefix-map (or -fmacro-prefix-map) flag is not added to TARGET_CFLAGS. Use this for packages where path remapping causes build failures.

no-mips16 — Disable MIPS16 instruction mode

Default behavior: MIPS16 is enabled for all packages when CONFIG_USE_MIPS16=y.

MIPS16 is a compressed 16-bit instruction encoding that reduces code size on MIPS targets at a small performance cost.

PKG_BUILD_FLAGS:=no-mips16

Use this for packages that are incompatible with MIPS16 mode (e.g., packages that use MIPS32-only assembly or inline asm that conflicts with MIPS16 interworking).

gc-sections — Enable dead code elimination

Default behavior: Controlled by CONFIG_USE_GC_SECTIONS. If the global config is off, gc-sections is off by default per package.

When enabled, the following flags are added:

TARGET_CFLAGS   += -ffunction-sections -fdata-sections
TARGET_CXXFLAGS += -ffunction-sections -fdata-sections
TARGET_LDFLAGS  += -Wl,--gc-sections

This places each function and data object in its own section, allowing the linker to discard unused sections, often significantly reducing binary size.

PKG_BUILD_FLAGS:=gc-sections

no-gc-sections — Disable dead code elimination

Default behavior: Follows CONFIG_USE_GC_SECTIONS.

Use this to explicitly disable gc-sections for a package even when the global CONFIG_USE_GC_SECTIONS=y setting is active.

PKG_BUILD_FLAGS:=no-gc-sections

Useful for packages where --gc-sections causes incorrect linking (e.g., packages with complex constructor/destructor dependencies or linker scripts that conflict).

lto — Enable Link Time Optimization

Default behavior: Controlled by CONFIG_USE_LTO. If the global config is off, LTO is off by default per package.

When enabled, the following flags are added (from include/package.mk):

TARGET_CFLAGS   += -flto=auto -fno-fat-lto-objects
TARGET_CXXFLAGS += -flto=auto -fno-fat-lto-objects
TARGET_LDFLAGS  += -flto=auto -fuse-linker-plugin

LTO allows GCC to optimize across object file boundaries during linking, which can improve performance and reduce binary size.

PKG_BUILD_FLAGS:=lto

Example usage: both ubus and procd use PKG_BUILD_FLAGS:=lto.

no-lto — Disable Link Time Optimization

Default behavior: Follows CONFIG_USE_LTO.

Explicitly disables LTO for a package even when CONFIG_USE_LTO=y.

PKG_BUILD_FLAGS:=no-lto

Use for packages that fail to build with LTO (e.g., packages with assembly code that is incompatible with LTO’s intermediate representation, or packages with broken build systems that don’t pass LTO flags to the linker).

no-mold — Disable mold linker

Default behavior: When CONFIG_USE_MOLD=y, the mold linker is used for all packages (the mold flag defaults to 1).

mold is a high-speed linker. When globally enabled, it replaces the default bfd linker.

PKG_BUILD_FLAGS:=no-mold

Use for packages that are incompatible with mold (e.g., packages that rely on BFD-specific linker script features or LTO plugin behavior).

Global Config Options

These CONFIG_ options set the system-wide defaults that the per-package flags override:

Config Symbol	Description
CONFIG_USE_MIPS16	Enable MIPS16 instructions globally (MIPS targets only)
CONFIG_USE_GC_SECTIONS	Enable --gc-sections globally for all packages
CONFIG_USE_LTO	Enable Link Time Optimization globally
CONFIG_USE_MOLD	Use the mold linker globally

Complete Example

# package/system/myapp/Makefile
include $(TOPDIR)/rules.mk

PKG_NAME:=myapp
PKG_VERSION:=1.0.0
PKG_RELEASE:=1

# Enable gc-sections and LTO; disable MIPS16 (has incompatible asm)
PKG_BUILD_FLAGS:=gc-sections lto no-mips16

include $(INCLUDE_DIR)/package.mk

define Package/myapp
  SECTION:=utils
  CATEGORY:=Utilities
  TITLE:=My Application
endef

$(eval $(call BuildPackage,myapp))

Unknown Flags

If PKG_BUILD_FLAGS contains an unrecognized value, the build will immediately error:

unknown PKG_BUILD_FLAGS: <flag-name>

The complete list of valid flags is defined in include/package.mk:

__unknown_flags=$(filter-out no-iremap no-mips16 gc-sections no-gc-sections lto no-lto no-mold,$(PKG_BUILD_FLAGS))