Expand $OUT_DIR in include_aseprite and include_background_gfx (#545)

As discussed in https://github.com/agbrs/agb/discussions/544, this
expand $OUT_DIR when used in the **include_aseprite** and
**include_background_gfx** macros in order to support including from the
out directory.

Example usage:
`const SPRITE_0: &Graphics =
include_aseprite!("$OUT_DIR/sprite_0.aseprite");`

- [x] Changelog updated / no changelog update needed

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- You can now use include_aseprite and include_background_gfx to include files from the out directory using the `$OUT_DIR` token.
+
 ## [0.18.0] - 2023/10/31
 
 ### Added

agb-image-converter/src/lib.rs

@@ -42,7 +42,9 @@ struct BackgroundGfxOption {
 
 impl config::Image for BackgroundGfxOption {
     fn filename(&self) -> String {
-        self.file_name.clone()
+        self.file_name
+            .clone()
+            .replace(OUT_DIR_TOKEN, &get_out_dir(&self.file_name))
     }
 
     fn colours(&self) -> Colours {
@@ -169,6 +171,15 @@ impl config::Config for IncludeBackgroundGfxInput {
     }
 }
 
+/// Including from the out directory is supported through the `$OUT_DIR` token.
+///
+/// ```rust,ignore
+/// # #![no_std]
+/// # #![no_main]
+/// # use agb::include_background_gfx;
+/// include_background_gfx!(generated_background, "000000", DATA => "$OUT_DIR/generated_background.aseprite");
+/// ```
+///
 #[proc_macro]
 pub fn include_background_gfx(input: TokenStream) -> TokenStream {
     let config = Box::new(parse_macro_input!(input as IncludeBackgroundGfxInput));
@@ -293,6 +304,8 @@ pub fn include_colours_inner(input: TokenStream) -> TokenStream {
 
 #[proc_macro]
 pub fn include_aseprite_inner(input: TokenStream) -> TokenStream {
+    let out_dir_path = get_out_dir(&input.to_string());
+
     let parser = Punctuated::<LitStr, syn::Token![,]>::parse_terminated;
     let parsed = match parser.parse(input) {
         Ok(e) => e,
@@ -310,6 +323,7 @@ pub fn include_aseprite_inner(input: TokenStream) -> TokenStream {
     let filenames: Vec<PathBuf> = parsed
         .iter()
         .map(|s| s.value())
+        .map(|s| s.replace(OUT_DIR_TOKEN, &out_dir_path))
         .map(|s| Path::new(&root).join(&*s))
         .collect();
 
@@ -663,6 +677,16 @@ fn valid_sprite_size(width: u32, height: u32) -> bool {
     }
 }
 
+const OUT_DIR_TOKEN: &str = "$OUT_DIR";
+
+fn get_out_dir(raw_input: &str) -> String {
+    if raw_input.contains(OUT_DIR_TOKEN) {
+        std::env::var("OUT_DIR").expect("Failed to get OUT_DIR")
+    } else {
+        String::new()
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use asefile::AnimationDirection;

agb/src/display/object/sprites/sprite.rs

@@ -91,6 +91,17 @@ macro_rules! align_bytes {
 /// name in code. You should ensure tags are unique as this is not enforced by
 /// aseprite.
 ///
+/// Including from the out directory is supported through the `$OUT_DIR` token.
+///
+/// ```rust,ignore
+/// # #![no_std]
+/// # #![no_main]
+/// # use agb::{display::object::Graphics, include_aseprite};
+/// const GRAPHICS: &Graphics = include_aseprite!(
+///     "$OUT_DIR/generated_sprite.aseprite"
+/// );
+/// ```
+///
 #[macro_export]
 macro_rules! include_aseprite {
     ($($aseprite_path: expr),*) => {{

agb/src/lib.rs

@@ -97,6 +97,15 @@
 /// bg.show();
 /// # }
 /// ```
+///
+/// Including from the out directory is supported through the `$OUT_DIR` token.
+///
+/// ```rust,ignore
+/// # #![no_std]
+/// # #![no_main]
+/// # use agb::include_background_gfx;
+/// include_background_gfx!(generated_background, "000000", DATA => "$OUT_DIR/generated_background.aseprite");
+/// ```
 pub use agb_image_converter::include_background_gfx;
 
 #[doc(hidden)]