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.