Rephrase PURGE documentation and raise the default level to 2

Fixes #1847
This commit is contained in:
Rangi42
2025-10-13 11:43:29 -04:00
parent 651877e094
commit aa672bbec9
3 changed files with 16 additions and 10 deletions

View File

@@ -441,10 +441,10 @@ or
.Fl Wno-purge
disables this warning.
.Fl Wpurge=1
or just
.Fl Wpurge
warns when purging any exported symbol (regardless of type).
.Fl Wpurge=2
or just
.Fl Wpurge
also warns when purging any label (even if not exported).
.It Fl Wshift
Warn when shifting right a negative value.

View File

@@ -1711,15 +1711,21 @@ Note also that only exported symbols will appear in symbol and map files produce
.Ss Purging symbols
.Ic PURGE
allows you to completely remove a symbol from the symbol table, as if it had never been defined.
.Bd -literal -offset indent
DEF value EQU 42
PURGE value
DEF value EQUS "I'm a string now"
ASSERT DEF(value)
PURGE value
ASSERT !DEF(value)
.Ed
.Pp
Be
.Em very
careful when purging symbols, especially labels, because it could result in unpredictable errors if something depends on the missing symbol (for example, expressions the linker needs to calculate).
.Bd -literal -offset indent
DEF Kamikaze EQUS "I don't want to live anymore"
AOLer: DB "Me too lol"
PURGE Kamikaze, AOLer
ASSERT !DEF(Kamikaze) && !DEF(AOLer)
.Ed
careful when purging symbols that have been referenced in section data, or that have been exported, because it could result in unpredictable errors if something depends on the missing symbol (for example, expressions the linker needs to calculate).
Purging labels at all is
.Em not
recommended.
.Pp
String constants are not expanded within the symbol names.
.Ss Predeclared symbols