Annotate deprecated C++ APIs

A `BN_DEPRECATED` macro is introduced that expands to a `[[deprecated(msg)]]`
attribute. Using functions that are annotated as deprecated will
generate a compiler warning. This should help make users aware that they
should migrate to replacement APIs.

3 files changed, 106 insertions, 11 deletions

diff --git a/base/compiler.h b/base/compiler.h
new file mode 100644
index 00000000..a61f59a0
--- /dev/null
+++ b/base/compiler.h
@@ -0,0 +1,73 @@
+// Copyright (c) 2026 Vector 35 Inc
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to
+// deal in the Software without restriction, including without limitation the
+// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+// sell copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+// IN THE SOFTWARE.
+
+#pragma once
+
+// Compiler-related defines
+
+// BN_DEPRECATED(msg) or BN_DEPRECATED(msg, replacement)
+//
+// Marks a declaration as deprecated with a message and optional replacement.
+//
+// For Clang with a replacement, expands to __attribute__((deprecated(msg, replacement)))
+// which provides both the deprecation message and a fix-it hint for the replacement.
+//
+// Otherwise, expands to [[deprecated(msg)]].
+
+#define __BN_DEPRECATED_WITH_MESSAGE(msg) [[deprecated(msg)]]
+#if defined(__clang__)
+#define __BN_DEPRECATED_WITH_REPLACEMENT(msg, replacement) __attribute__((deprecated(msg, replacement)))
+#else
+#define __BN_DEPRECATED_WITH_REPLACEMENT(msg, replacement) [[deprecated(msg)]]
+#endif
+
+#define __BN_DEPRECATED_GET_MACRO(_1, _2, NAME, ...) NAME
+#define __BN_DEPRECATED_EXPAND(x) x
+#define BN_DEPRECATED(...) __BN_DEPRECATED_EXPAND(__BN_DEPRECATED_GET_MACRO(__VA_ARGS__, __BN_DEPRECATED_WITH_REPLACEMENT, __BN_DEPRECATED_WITH_MESSAGE)(__VA_ARGS__))
+
+// BN_IGNORE_WARNINGS_BEGIN(gcc_warning, msvc_num) / BN_IGNORE_WARNINGS_END
+//
+// Suppresses a specific warning within a block of code.
+//
+// gcc_warning: A GCC/Clang warning flag as a string, e.g. "-Wdeprecated-declarations"
+// msvc_num: An MSVC warning number, e.g. 4996
+
+#if defined(_MSC_VER)
+#define BN_IGNORE_WARNINGS_BEGIN(gcc_warning, msvc_num) \
+    __pragma(warning(push)) \
+    __pragma(warning(disable: msvc_num))
+#define BN_IGNORE_WARNINGS_END __pragma(warning(pop))
+#elif defined(__clang__) || defined(__GNUC__)
+#define __BN_PRAGMA(x) _Pragma(#x)
+#define BN_IGNORE_WARNINGS_BEGIN(gcc_warning, msvc_num) \
+    _Pragma("GCC diagnostic push") \
+    __BN_PRAGMA(GCC diagnostic ignored gcc_warning)
+#define BN_IGNORE_WARNINGS_END _Pragma("GCC diagnostic pop")
+#else
+#define BN_IGNORE_WARNINGS_BEGIN(gcc_warning, msvc_num)
+#define BN_IGNORE_WARNINGS_END
+#endif
+
+// BN_IGNORE_DEPRECATION_WARNINGS_BEGIN / BN_IGNORE_DEPRECATION_WARNINGS_END
+//
+// Suppresses deprecation warnings within a block of code.
+
+#define BN_IGNORE_DEPRECATION_WARNINGS_BEGIN BN_IGNORE_WARNINGS_BEGIN("-Wdeprecated-declarations", 4996)
+#define BN_IGNORE_DEPRECATION_WARNINGS_END BN_IGNORE_WARNINGS_END
diff --git a/binaryninjaapi.h b/binaryninjaapi.h
index 64753e55..5c73fe9a 100644
--- a/binaryninjaapi.h
+++ b/binaryninjaapi.h
@@ -26,6 +26,15 @@
 	#include <windows.h>
 	#define FMT_UNICODE 0
 #endif
+
+#include "base/compiler.h"
+#include "binaryninjacore.h"
+#include "exceptions.h"
+
+#include "json/json.h"
+#include "rapidjsonwrapper.h"
+#include "vendor/nlohmann/json.hpp"
+
 #include <cstddef>
 #include <string>
 #include <vector>
@@ -41,15 +50,9 @@
 #include <cstdint>
 #include <typeinfo>
 #include <type_traits>
-#include <variant>
 #include <optional>
 #include <memory>
 #include <any>
-#include "binaryninjacore.h"
-#include "exceptions.h"
-#include "json/json.h"
-#include "rapidjsonwrapper.h"
-#include "vendor/nlohmann/json.hpp"
 #include <fmt/format.h>
 #include <fmt/ranges.h>
 #include <fmt/core.h>
@@ -1968,11 +1971,13 @@ namespace BinaryNinja {
 	/*!
 		\deprecated Use `InitPlugins()`
 	*/
-	void InitCorePlugins();  // Deprecated, use InitPlugins
+	BN_DEPRECATED("Use InitPlugins", "InitPlugins")
+	void InitCorePlugins();
 	/*!
 		\deprecated Use `InitPlugins()`
 	*/
-	void InitUserPlugins();  // Deprecated, use InitPlugins
+	BN_DEPRECATED("Use InitPlugins", "InitPlugins")
+	void InitUserPlugins();
 	void InitRepoPlugins();
 
 	std::string GetBundledPluginDirectory();
@@ -6048,6 +6053,7 @@ namespace BinaryNinja {
 
 		    \return the original image base of the BinaryView
 		*/
+		BN_DEPRECATED("Use GetOriginalImageBase", "GetOriginalImageBase")
 		uint64_t GetOriginalBase() const;
 
 		/*! SetOriginalBase sets the original image base in the BinaryView, unaffected by any rebasing operations.
@@ -6057,6 +6063,7 @@ namespace BinaryNinja {
 
 		    \param base the original image base of the binary view
 		*/
+		BN_DEPRECATED("Use SetOriginalImageBase", "SetOriginalImageBase")
 		void SetOriginalBase(uint64_t base);
 
 		/*! GetStart queries for the first valid virtual address in the BinaryView
@@ -6878,6 +6885,7 @@ namespace BinaryNinja {
 
 			\deprecated Prefer \c BulkSymbolModification for bulk symbol modifications.
 		*/
+		BN_DEPRECATED("Prefer BulkSymbolModification for bulk symbol modifications")
 		void BeginBulkModifySymbols();
 
 		/*! Finish an operation that potentially modified many symbols
@@ -6888,6 +6896,7 @@ namespace BinaryNinja {
 
 			\deprecated Prefer \c BulkSymbolModification for bulk symbol modifications.
 		*/
+		BN_DEPRECATED("Prefer BulkSymbolModification for bulk symbol modifications")
 		void EndBulkModifySymbols();
 
 		/*! Add a new TagType to this binaryview
@@ -7948,6 +7957,7 @@ namespace BinaryNinja {
 
 			\return The list of allocated ranges
 		*/
+		BN_DEPRECATED("Use GetMappedAddressRanges", "GetMappedAddressRanges")
 		std::vector<BNAddressRange> GetAllocatedRanges();
 
 		/*! Get the list of ranges mapped into the address space
@@ -8340,19 +8350,25 @@ namespace BinaryNinja {
 		BulkSymbolModification(Ref<BinaryView> view)
 			: m_view(std::move(view))
 		{
+			BN_IGNORE_DEPRECATION_WARNINGS_BEGIN
 			m_view->BeginBulkModifySymbols();
+			BN_IGNORE_DEPRECATION_WARNINGS_END
 		}
 
 		~BulkSymbolModification()
 		{
+			BN_IGNORE_DEPRECATION_WARNINGS_BEGIN
 			if (m_view)
 				m_view->EndBulkModifySymbols();
+			BN_IGNORE_DEPRECATION_WARNINGS_END
 		}
 
 		/*! End this bulk modification early. */
 		void End()
 		{
+			BN_IGNORE_DEPRECATION_WARNINGS_BEGIN
 			m_view->EndBulkModifySymbols();
+			BN_IGNORE_DEPRECATION_WARNINGS_END
 			m_view = nullptr;
 		}
 
@@ -8513,6 +8529,7 @@ namespace BinaryNinja {
 			\param arch Architecture to register this platform with
 			\param platform The Platform to register
 		*/
+		BN_DEPRECATED("Use RegisterPlatform overload without Architecture argument")
 		static void RegisterPlatform(const std::string& name, uint32_t id, Architecture* arch, Platform* platform);
 
 		/*! Register a Platform as a default for a specific view type
@@ -9947,12 +9964,15 @@ namespace BinaryNinja {
 		// have been removed, and they now have no effects.
 		/*! \deprecated This API has been deprecated. The implementation has been removed, and this function no longer has any effect
 		*/
+		BN_DEPRECATED("This function no longer has any effect")
 		bool IsBinaryViewTypeConstantDefined(const std::string& type, const std::string& name);
 		/*! \deprecated This API has been deprecated. The implementation has been removed, and this function no longer has any effect
 		*/
+		BN_DEPRECATED("This function no longer has any effect")
 		uint64_t GetBinaryViewTypeConstant(const std::string& type, const std::string& name, uint64_t defaultValue = 0);
 		/*! \deprecated This API has been deprecated. The implementation has been removed, and this function no longer has any effect
 		*/
+		BN_DEPRECATED("This function no longer has any effect")
 		void SetBinaryViewTypeConstant(const std::string& type, const std::string& name, uint64_t value);
 
 		/*! Register a calling convention with this architecture
@@ -11842,6 +11862,7 @@ namespace BinaryNinja {
 			\param name Workflow name
 			\return The workflow.
 		*/
+		BN_DEPRECATED("Use Workflow::Get or Workflow::GetOrCreate instead.")
 		static Ref<Workflow> Instance(const std::string& name = "") { return GetOrCreate(name); }
 
 		/*! Register a workflow, making it immutable and available for use
@@ -20621,6 +20642,7 @@ namespace BinaryNinja {
 		/*!
 			\deprecated Use `ParseTypeString` with the extra `importDependencies` param
 		 */
+		BN_DEPRECATED("Use ParseTypeString overload with the extra importDependencies param")
 		bool ParseTypeString(
 			const std::string& source,
 			QualifiedNameAndType& result,
@@ -20654,6 +20676,7 @@ namespace BinaryNinja {
 		/*!
 			\deprecated Use `ParseTypesFromSource` with the extra `importDependencies` param
 		 */
+		BN_DEPRECATED("Use ParseTypesFromSource overload with the extra importDependencies param")
 		bool ParseTypesFromSource(
 			const std::string& text,
 			const std::string& fileName,
diff --git a/platform/linux/platform_linux.cpp b/platform/linux/platform_linux.cpp
index 796df353..7f625c06 100644
--- a/platform/linux/platform_linux.cpp
+++ b/platform/linux/platform_linux.cpp
@@ -436,9 +436,8 @@ extern "C"
 			Platform::Register("linux", g_linuxX32);
 
 			// Linux binaries sometimes have an OS identifier of zero, even though 3 is the correct one
-			BinaryViewType::RegisterPlatform("ELF", 0, x64, x64Platform);
-			BinaryViewType::RegisterPlatform("ELF", 3, x64, x64Platform);
-
+			BinaryViewType::RegisterPlatform("ELF", 0, x64Platform);
+			BinaryViewType::RegisterPlatform("ELF", 3, x64Platform);
 
 			Ref<BinaryViewType> elf = BinaryViewType::GetByName("ELF");
 			if (elf)