ld "unrecognized option / cannot open linker script" in CI

By Kaveh Alemi·Latchkey

A -T option tells ld to use a custom linker script. If that path does not exist on the runner, ld stops with "cannot open linker script", naming the file it could not open.

What this error means

An embedded or custom-layout link fails because the .ld script passed with -T is missing, often a path relative to a directory that differs in CI.

/usr/bin/ld: cannot open linker script file linker.ld:
No such file or directory
collect2: error: ld returned 1 exit status

Common causes

How to fix it

Pass an absolute or correct path

1. Resolve the linker script to a path that exists in the CI working tree.
2. Pass it to ld and relink.

gcc main.o -o app -T "$PWD/ld/linker.ld"

Generate or fetch the script first

Ensure the step that produces the script (or the submodule that holds it) runs before the link.

git submodule update --init --recursive
cmake --build build

How to prevent it

• Reference linker scripts by a path that is stable in CI and make sure any step or submodule that provides the script runs before the link.

Frequently asked questions

Related guides

References

• CMake documentation
• GitHub Actions documentation