From df85f9864f4ad9d2deb6a953107b916d701f7c1b Mon Sep 17 00:00:00 2001 From: Nick Clifton Date: Mon, 24 Jun 2024 15:00:14 +0100 Subject: ld: Improve the documentation describing the -o option. PR 31761 --- ld/ld.texi | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/ld/ld.texi b/ld/ld.texi index cc0a37d..2eafeb7 100644 --- a/ld/ld.texi +++ b/ld/ld.texi @@ -994,6 +994,28 @@ Use @var{output} as the name for the program produced by @command{ld}; if this option is not specified, the name @file{a.out} is used by default. The script command @code{OUTPUT} can also specify the output file name. +Note - the linker will delete the output file before it starts to +write to it. It will do this even if it turns out that the link +cannot be completed due to errors. + +Note - the linker will check to make sure that the output file name +does not match the name of any of the input files, but that is all. +In particular it will not complain if the output file might overwrite +a source file or some other important file. Therefore in build +systems it is recommended to use the @option{-o} option as the last +option on the linker command line. For example consider: + +@smallexample + ld -o $(EXE) $(OBJS) + ld $(OBJS) -o $(EXE) +@end smallexample + +If the @samp{EXE} variable is not defined for some reason, the first +version of the linker command could end up deleting one of the object +files (the first one in the @samp{OBJS} list) whereas the second +version of the linker command will generate an error message and not +delete anything. + @kindex --dependency-file=@var{depfile} @cindex dependency file @item --dependency-file=@var{depfile} -- cgit v1.1