From aa672bbec91611f903bd5e29e59358ae4dd438c4 Mon Sep 17 00:00:00 2001 From: Rangi42 Date: Mon, 13 Oct 2025 11:43:29 -0400 Subject: [PATCH] Rephrase `PURGE` documentation and raise the default level to 2 Fixes #1847 --- man/rgbasm.1 | 4 ++-- man/rgbasm.5 | 20 +++++++++++++------- src/asm/warning.cpp | 2 +- 3 files changed, 16 insertions(+), 10 deletions(-) diff --git a/man/rgbasm.1 b/man/rgbasm.1 index 8b22b47e..5f05bdda 100644 --- a/man/rgbasm.1 +++ b/man/rgbasm.1 @@ -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. diff --git a/man/rgbasm.5 b/man/rgbasm.5 index 13d7de74..64df96ab 100644 --- a/man/rgbasm.5 +++ b/man/rgbasm.5 @@ -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 diff --git a/src/asm/warning.cpp b/src/asm/warning.cpp index a3772004..91ba5f62 100644 --- a/src/asm/warning.cpp +++ b/src/asm/warning.cpp @@ -52,7 +52,7 @@ Diagnostics warnings = { }, .paramWarnings = { {WARNING_NUMERIC_STRING_1, WARNING_NUMERIC_STRING_2, 1}, - {WARNING_PURGE_1, WARNING_PURGE_2, 1}, + {WARNING_PURGE_1, WARNING_PURGE_2, 2}, {WARNING_TRUNCATION_1, WARNING_TRUNCATION_2, 2}, {WARNING_UNMAPPED_CHAR_1, WARNING_UNMAPPED_CHAR_2, 1}, },