Linker Scripts#

pw_build: Integrations for Bazel, GN, and CMake

pw_build provides utilities for working with linker scripts in embedded projects. If using the GN or Bazel build systems you can preprocess your linker script using the C preprocessor with the pw_linker_script rules.

Linker Script Helpers#

PW_MUST_PLACE#

PW_MUST_PLACE(isection)#

PW_MUST_PLACE is a macro intended for use in linker scripts to ensure inputs are non-zero sized.

Say you want to place a specific object file into a particular section. You can reference it by file path like:

SECTIONS
{
  .special_code
  {
    */src/path/libspecial_code.a:*.o
  }
}

This works but is fragile as it will silently break if the filename or path changes. Use PW_MUST_PLACE to get a linker assertion if the input is empty.

#include "pw_build/must_place.ld.h"

SECTIONS
{
  .special_code
  {
    PW_MUST_PLACE(*/src/path/libspecial_code.a:*.o)
  }
}

If the wildcard match fails PW_MUST_PLACE will generate an error telling you which input had no symbols.

Error: No symbols found in pattern below
*/src/path/libspecial_code.a:*.o

This could be because you had a typo, the path changed, or the symbols were dropped due to linker section garbage collection.In the latter case, you can choose to add KEEP() around your input to prevent garbage collection.

On this page