package-metadata: Add macro to define program id from Cargo.toml (#1806

)

* package-metadata: Add package and macro

* Use the macro in a program as a test

* Move test to cargo-build-sbf, update version

* Add changelog entry

* Revert simulation change

CHANGELOG.md

@@ -37,6 +37,19 @@ or
 tools-version = "1.43"
 ```
 The order of precedence for the chosen tools version goes: `--tools-version` argument, package version, workspace version, and finally default version.
+  * `package-metadata`: specify a program's id in Cargo.toml for easy consumption by downstream users and tools using `solana-package-metadata` (#1806). For example:
+```toml
+[package.metadata.solana]
+program-id = "MyProgram1111111111111111111111111111111111"
+```
+Can be consumed in the program crate:
+```rust
+solana_package_metadata::declare_id_with_package_metadata!("solana.program-id");
+```
+This is equivalent to writing:
+```rust
+solana_pubkey::declare_id!("MyProgram1111111111111111111111111111111111");
+```
   * `agave-validator`: Update PoH speed check to compare against current hash rate from a Bank (#2447)
   * `solana-test-validator`: Add `--clone-feature-set` flag to mimic features from a target cluster (#2480)
   * `solana-genesis`: the `--cluster-type` parameter now clones the feature set from the target cluster (#2587)

Cargo.toml

@@ -117,6 +117,7 @@ members = [
     "sdk/instruction",
     "sdk/macro",
     "sdk/msg",
+    "sdk/package-metadata",
     "sdk/package-metadata-macro",
     "sdk/program",
     "sdk/program-error",
@@ -434,6 +435,7 @@ solana-msg = { path = "sdk/msg", version = "=2.1.0" }
 solana-net-utils = { path = "net-utils", version = "=2.1.0" }
 solana-nohash-hasher = "0.2.1"
 solana-notifier = { path = "notifier", version = "=2.1.0" }
+solana-package-metadata = { path = "sdk/package-metadata", version = "=2.1.0" }
 solana-package-metadata-macro = { path = "sdk/package-metadata-macro", version = "=2.1.0" }
 solana-perf = { path = "perf", version = "=2.1.0" }
 solana-poh = { path = "poh", version = "=2.1.0" }

sdk/cargo-build-sbf/tests/crates/package-metadata/Cargo.toml

@@ -11,8 +11,10 @@ publish = false
 
 [package.metadata.solana]
 tools-version = "v1.43"
+program-id = "MyProgram1111111111111111111111111111111111"
 
 [dependencies]
+solana-package-metadata = { path = "../../../../package-metadata", version = "=2.1.0" }
 solana-program = { path = "../../../../program", version = "=2.1.0" }
 
 [lib]

sdk/cargo-build-sbf/tests/crates/package-metadata/src/lib.rs

@@ -2,6 +2,7 @@
 
 use solana_program::{account_info::AccountInfo, entrypoint::ProgramResult, pubkey::Pubkey};
 
+solana_package_metadata::declare_id_with_package_metadata!("solana.program-id");
 solana_program::entrypoint!(process_instruction);
 fn process_instruction(
     _program_id: &Pubkey,

sdk/package-metadata/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "solana-package-metadata"
+description = "Solana Package Metadata"
+documentation = "https://docs.rs/solana-package-metadata"
+version = { workspace = true }
+authors = { workspace = true }
+repository = { workspace = true }
+homepage = { workspace = true }
+license = { workspace = true }
+edition = { workspace = true }
+
+[dependencies]
+solana-package-metadata-macro = { workspace = true }
+solana-pubkey = { workspace = true }
+
+[package.metadata.docs.rs]
+targets = ["x86_64-unknown-linux-gnu"]

sdk/package-metadata/src/lib.rs

@@ -0,0 +1,90 @@
+/// Macro for accessing data from the `package.metadata` section of the Cargo manifest
+///
+/// # Arguments
+/// * `key` - A string slice of a dot-separated path to the TOML key of interest
+///
+/// # Example
+/// Given the following `Cargo.toml`:
+/// ```ignore
+/// [package]
+/// name = "MyApp"
+/// version = "0.1.0"
+///
+/// [package.metadata]
+/// copyright = "Copyright (c) 2024 ACME Inc."
+/// ```
+///
+/// You can fetch the copyright with the following:
+/// ```ignore
+/// use solana_package_metadata::package_metadata;
+///
+/// pub fn main() {
+///     let copyright = package_metadata!("copyright");
+///     assert_eq!(copyright, "Copyright (c) 2024 ACME Inc.");
+/// }
+/// ```
+///
+/// ## TOML Support
+/// This macro only supports static data:
+/// * Strings
+/// * Integers
+/// * Floating-point numbers
+/// * Booleans
+/// * Datetimes
+/// * Arrays
+///
+/// ## Array Example
+/// Given the following Cargo manifest:
+/// ```ignore
+/// [package.metadata.arrays]
+/// some_array = [ 1, 2, 3 ]
+/// ```
+///
+/// This is legal:
+/// ```ignore
+/// static ARR: [i64; 3] = package_metadata!("arrays.some_array");
+/// ```
+///
+/// It does *not* currently support accessing TOML array elements directly.
+/// TOML tables are not supported.
+pub use solana_package_metadata_macro::package_metadata;
+/// Re-export solana_pubkey::declare_id for easy usage within the macro
+pub use solana_pubkey::declare_id;
+
+/// Convenience macro for declaring a program id from Cargo.toml package metadata.
+///
+/// # Arguments
+/// * `key` - A string slice of a dot-separated path to the TOML key of interest
+///
+/// # Example
+/// Given the following `Cargo.toml`:
+/// ```ignore
+/// [package]
+/// name = "my-solana-program"
+/// version = "0.1.0"
+///
+/// [package.metadata.solana]
+/// program-id = "MyProgram1111111111111111111111111111111111"
+/// ```
+///
+/// A program can use the program id declared in its `Cargo.toml` as the program
+/// id in code:
+///
+/// ```ignore
+/// declare_id_with_package_metadata!("solana.program-id");
+/// ```
+///
+/// This program id behaves exactly as if the developer had written:
+///
+/// ```
+/// solana_pubkey::declare_id!("MyProgram1111111111111111111111111111111111");
+/// ```
+///
+/// Meaning that it's possible to refer to the program id using `crate::id()`,
+/// without needing to specify the program id in multiple places.
+#[macro_export]
+macro_rules! declare_id_with_package_metadata {
+    ($key:literal) => {
+        $crate::declare_id!($crate::package_metadata!($key));
+    };
+}