Gathering Data to Optimize Bevy Binary Sizes and Compile Times

[cart]

Random thing I got sidetracked on: I think its worthwhile to go through all of our generic / monomorphized code to try to find areas where we can "hoist out" the generic parts to cut down on our code gen, which would ideally both reduce binary sizes and compile times.

cargo bloat is a tool that lets you see what functions are the "biggest", however to my knowledge, it doesn't have the ability to combine the data for all functions with the same name / path (aka, all outputs produced for a given generic function).

So I built a simple tool that reads the json output of cargo bloat, combines functions with the same name, and sorts by total size.

I dumped the cargo bloat results for 3d_scene using:

 cargo bloat --release --example 3d_scene -n 100000 --message-format json > out.json

Then ran those results through my tool linked above.

Here are the top results (sorted smallest to largest) for 3d_scene. The tuple is (name, total size in bytes, percentage of .text section). Note that this methodology will also combine results across trait impls, so for each case, consider if this is combining results across trait impls or generic function impls (ex: PartialReflect::apply is combined across all trait impls, EntityWorldMut::insert_with_caller is combined across all generic function impls). The total size of the 3d_scene release binary (not stripped) is 82.2 MiB. This size of the .text section (the "actual binary code") is 32.5 MiB:

Top 25-ish Combined Results For 3d_scene

(
    "bevy_reflect::reflect::PartialReflect::apply",
    163759,
    0.48035568,
),
(
    "<bevy_reflect::enums::dynamic_enum::DynamicEnum as bevy_reflect::reflect::PartialReflect>::try_apply",
    164006,
    0.4810802,
),
(
    "bevy_reflect::impls::std::_::<impl bevy_reflect::reflect::PartialReflect for core::option::Option<T>>::try_apply",
    165017,
    0.4840458,
),
(
    "<arrayvec::arrayvec::ArrayVec<T,_> as core::iter::traits::collect::FromIterator<T>>::from_iter",
    184009,
    0.53975517,
),
(
    "<alloc::vec::Vec<T> as alloc::vec::spec_from_iter::SpecFromIter<T,I>>::from_iter",
    184300,
    0.54060876,
),
(
    "hashbrown::raw::inner::RawTableInner::drop_inner_table",
    186388,
    0.54673356,
),
(
    "bevy_reflect::struct_trait::StructInfo::new",
    201430,
    0.5908564,
),
(
    "<&T as core::fmt::Debug>::fmt",
    207636,
    0.60906047,
),
(
    "bevy_ecs::reflect::from_reflect_with_fallback",
    208477,
    0.6115274,
),
(
    "<dyn bevy_reflect::reflect::Reflect>::take",
    208866,
    0.61266845,
),
(
    "bevy_reflect::type_registry::TypeRegistry::register",
    209310,
    0.6139708,
),
(
    "bevy_ecs::query::state::QueryState<D,F>::new_archetype_internal",
    218591,
    0.6411949,
),
(
    "bevy_asset::handle::_::<impl bevy_reflect::reflect::PartialReflect for bevy_asset::handle::Handle<A>>::try_apply",
    229152,
    0.67217356,
),
(
    "<bevy_ecs::system::function_system::FunctionSystem<Marker,F> as bevy_ecs::system::system::System>::initialize",
    251927,
    0.73897964,
),
(
    "<&mut serde_json::de::Deserializer<R> as serde::de::Deserializer>::deserialize_struct",
    253932,
    0.74486095,
),
(
    "bevy_asset::id::_::<impl bevy_reflect::reflect::PartialReflect for bevy_asset::id::AssetId<A>>::try_apply",
    263421,
    0.7726951,
),
(
    "<bevy_ecs::change_detection::Res<T> as bevy_ecs::system::system_param::SystemParam>::init_state",
    291551,
    0.85520905,
),
(
    "bevy_ecs::system::system::System::run",
    306162,
    0.89806765,
),
(
    "<bevy_ecs::change_detection::ResMut<T> as bevy_ecs::system::system_param::SystemParam>::init_state",
    322248,
    0.94525284,
),
(
    "<bevy_ecs::system::function_system::FunctionSystem<Marker,F> as bevy_ecs::system::system::System>::run_unsafe",
    351817,
    1.0319879,
),
(
    "core::ops::function::impls::<impl core::ops::function::FnMut<A> for &mut F>::call_mut",
    383327,
    1.1244164,
),
(
    "bevy_ecs::world::entity_ref::EntityWorldMut::insert_with_caller",
    391176,
    1.14744,
),
(
    "std::sys::sync::once::futex::Once::call",
    638082,
    1.8716915,
),
(
    "bevy_reflect::utility::GenericTypeCell<T>::get_or_insert",
    654473,
    1.9197713,
),
(
    "hashbrown::raw::inner::RawTable<T,A>::reserve_rehash",
    1029876,
    3.020944,
),
(
    "core::ops::function::FnOnce::call_once",
    1189280,
    3.4885254,
),

From there, I chose to try naively optimizing EntityWorldMut::insert_with_caller by factoring out the relevant parts that aren't generic. This is almost certainly not viable, given that it relies on allocating a Box / using dynamic dispatch, but it does help make a point. This saved 0.5 MiB in a release build (which is interestingly slightly larger than the reported 0.373 MiB for EntityWorldMut::insert_with_caller). I could not detect meaningful compile time differences. Is suspect the win is there, but it is small enough that it is covered by noise for small sample sizes.

Naive "hoisted" insert optimization

    #[inline]
    pub(crate) unsafe fn insert<T: DynamicBundle + 'static>(
        &mut self,
        entity: Entity,
        location: EntityLocation,
        bundle: T,
        insert_mode: InsertMode,
        #[cfg(feature = "track_change_detection")] caller: &'static Location<'static>,
    ) -> EntityLocation {
        let mut write_bundle = |bundle_info: &BundleInfo,
                                table: &mut Table,
                                sparse_sets: &mut SparseSets,
                                add_bundle: &AddBundle,
                                entity: Entity,
                                table_row: TableRow,
                                change_tick: Tick,
                                insert_mode: InsertMode| {
            bundle_info.write_components(
                table,
                sparse_sets,
                add_bundle,
                add_bundle.required_components.iter(),
                entity,
                table_row,
                change_tick,
                bundle,
                insert_mode,
                #[cfg(feature = "track_change_detection")]
                caller,
            );
        };

        self.insert_flat(entity, location, insert_mode, Box::new(write_bundle))
    }

    /// # Safety
    /// `entity` must currently exist in the source archetype for this inserter. `location`
    /// must be `entity`'s location in the archetype. `T` must match this [`BundleInfo`]'s type
    #[inline(never)]
    unsafe fn insert_flat(
        &mut self,
        entity: Entity,
        location: EntityLocation,
        insert_mode: InsertMode,
        write_bundle: Box<
            dyn FnOnce(
                    &BundleInfo,
                    &mut Table,
                    &mut SparseSets,
                    &AddBundle,
                    Entity,
                    TableRow,
                    Tick,
                    InsertMode,
                ) + 'static,
        >,
    ) -> EntityLocation {
        let bundle_info = self.bundle_info.as_ref();
        let add_bundle = self.add_bundle.as_ref();
        let table = self.table.as_mut();
        let archetype = self.archetype.as_ref();

        // SAFETY: All components in the bundle are guaranteed to exist in the World
        // as they must be initialized before creating the BundleInfo.
        unsafe {
            // SAFETY: Mutable references do not alias and will be dropped after this block
            let mut deferred_world = self.world.into_deferred();

            if insert_mode == InsertMode::Replace {
                deferred_world.trigger_on_replace(archetype, entity, add_bundle.iter_existing());
                if archetype.has_replace_observer() {
                    deferred_world.trigger_observers(
                        ON_REPLACE,
                        entity,
                        add_bundle.iter_existing(),
                    );
                }
            }
        }

        // SAFETY: Archetype gets borrowed when running the on_replace observers above,
        // so this reference can only be promoted from shared to &mut down here, after they have been ran
        let archetype = self.archetype.as_mut();

        let (new_archetype, new_location) = match &mut self.result {
            InsertBundleResult::SameArchetype => {
                // SAFETY: Mutable references do not alias and will be dropped after this block
                let sparse_sets = {
                    let world = self.world.world_mut();
                    &mut world.storages.sparse_sets
                };

                (write_bundle)(
                    bundle_info,
                    table,
                    sparse_sets,
                    add_bundle,
                    entity,
                    location.table_row,
                    self.change_tick,
                    insert_mode,
                );

                (archetype, location)
            }
            InsertBundleResult::NewArchetypeSameTable { new_archetype } => {
                let new_archetype = new_archetype.as_mut();

                // SAFETY: Mutable references do not alias and will be dropped after this block
                let (sparse_sets, entities) = {
                    let world = self.world.world_mut();
                    (&mut world.storages.sparse_sets, &mut world.entities)
                };

                let result = archetype.swap_remove(location.archetype_row);
                if let Some(swapped_entity) = result.swapped_entity {
                    let swapped_location =
                        // SAFETY: If the swap was successful, swapped_entity must be valid.
                        unsafe { entities.get(swapped_entity).debug_checked_unwrap() };
                    entities.set(
                        swapped_entity.index(),
                        EntityLocation {
                            archetype_id: swapped_location.archetype_id,
                            archetype_row: location.archetype_row,
                            table_id: swapped_location.table_id,
                            table_row: swapped_location.table_row,
                        },
                    );
                }
                let new_location = new_archetype.allocate(entity, result.table_row);
                entities.set(entity.index(), new_location);

                (write_bundle)(
                    bundle_info,
                    table,
                    sparse_sets,
                    add_bundle,
                    entity,
                    result.table_row,
                    self.change_tick,
                    insert_mode,
                );

                (new_archetype, new_location)
            }
            InsertBundleResult::NewArchetypeNewTable {
                new_archetype,
                new_table,
            } => {
                let new_table = new_table.as_mut();
                let new_archetype = new_archetype.as_mut();

                // SAFETY: Mutable references do not alias and will be dropped after this block
                let (archetypes_ptr, sparse_sets, entities) = {
                    let world = self.world.world_mut();
                    let archetype_ptr: *mut Archetype = world.archetypes.archetypes.as_mut_ptr();
                    (
                        archetype_ptr,
                        &mut world.storages.sparse_sets,
                        &mut world.entities,
                    )
                };
                let result = archetype.swap_remove(location.archetype_row);
                if let Some(swapped_entity) = result.swapped_entity {
                    let swapped_location =
                        // SAFETY: If the swap was successful, swapped_entity must be valid.
                        unsafe { entities.get(swapped_entity).debug_checked_unwrap() };
                    entities.set(
                        swapped_entity.index(),
                        EntityLocation {
                            archetype_id: swapped_location.archetype_id,
                            archetype_row: location.archetype_row,
                            table_id: swapped_location.table_id,
                            table_row: swapped_location.table_row,
                        },
                    );
                }
                // PERF: store "non bundle" components in edge, then just move those to avoid
                // redundant copies
                let move_result = table.move_to_superset_unchecked(result.table_row, new_table);
                let new_location = new_archetype.allocate(entity, move_result.new_row);
                entities.set(entity.index(), new_location);

                // if an entity was moved into this entity's table spot, update its table row
                if let Some(swapped_entity) = move_result.swapped_entity {
                    let swapped_location =
                        // SAFETY: If the swap was successful, swapped_entity must be valid.
                        unsafe { entities.get(swapped_entity).debug_checked_unwrap() };

                    entities.set(
                        swapped_entity.index(),
                        EntityLocation {
                            archetype_id: swapped_location.archetype_id,
                            archetype_row: swapped_location.archetype_row,
                            table_id: swapped_location.table_id,
                            table_row: result.table_row,
                        },
                    );

                    if archetype.id() == swapped_location.archetype_id {
                        archetype
                            .set_entity_table_row(swapped_location.archetype_row, result.table_row);
                    } else if new_archetype.id() == swapped_location.archetype_id {
                        new_archetype
                            .set_entity_table_row(swapped_location.archetype_row, result.table_row);
                    } else {
                        // SAFETY: the only two borrowed archetypes are above and we just did collision checks
                        (*archetypes_ptr.add(swapped_location.archetype_id.index()))
                            .set_entity_table_row(swapped_location.archetype_row, result.table_row);
                    }
                }

                (write_bundle)(
                    bundle_info,
                    new_table,
                    sparse_sets,
                    add_bundle,
                    entity,
                    move_result.new_row,
                    self.change_tick,
                    insert_mode,
                );

                (new_archetype, new_location)
            }
        };

        let new_archetype = &*new_archetype;
        // SAFETY: We have no outstanding mutable references to world as they were dropped
        let mut deferred_world = unsafe { self.world.into_deferred() };

        // SAFETY: All components in the bundle are guaranteed to exist in the World
        // as they must be initialized before creating the BundleInfo.
        unsafe {
            deferred_world.trigger_on_add(new_archetype, entity, add_bundle.iter_added());
            if new_archetype.has_add_observer() {
                deferred_world.trigger_observers(ON_ADD, entity, add_bundle.iter_added());
            }
            match insert_mode {
                InsertMode::Replace => {
                    // insert triggers for both new and existing components if we're replacing them
                    deferred_world.trigger_on_insert(
                        new_archetype,
                        entity,
                        add_bundle.iter_inserted(),
                    );
                    if new_archetype.has_insert_observer() {
                        deferred_world.trigger_observers(
                            ON_INSERT,
                            entity,
                            add_bundle.iter_inserted(),
                        );
                    }
                }
                InsertMode::Keep => {
                    // insert triggers only for new components if we're not replacing them (since
                    // nothing is actually inserted).
                    deferred_world.trigger_on_insert(
                        new_archetype,
                        entity,
                        add_bundle.iter_added(),
                    );
                    if new_archetype.has_insert_observer() {
                        deferred_world.trigger_observers(
                            ON_INSERT,
                            entity,
                            add_bundle.iter_added(),
                        );
                    }
                }
            }
        }

        new_location
    }

Now obviously saving 0.6% binary size isn't a drastic win, but this does show that we have the ability to optimize linear-scaling / highly trafficked apis.

This is also a "death by 1000 papercuts" situation where we won't see big progress unless we optimize many cases. I suspect there is enough room here to make meaningful progress.

We also need to make sure that we aren't hamstringing performance when we do this. My naive EntityWorldMut::insert_with_caller change would show up on benchmarks.

[cart]

I need to move on for now, but if someone wants to pick this up and investigate further, that would be much appreciated!

[tbillington]

There is also this tool which shows duplicate functions output in the binary https://github.com/davidlattimore/duplicate-function-checker.

[cart]

Interesting. Seems like the distinction is that this tool finds "true redundancies" ... multiple functions that each produced the exact same machine code outputs, whereas my methodology above finds any function that is producing lots of code. Definitely a place for both tools!

[bushrat011899]

A really interesting initiative! I had a play with cargo bloat and your analysis tool and managed to shave 0.4MB off the same example by splitting GenericTypeCell::get_or_insert into a couple of smaller functions which don't require as many generic arguments. I've drafted a PR as #14865 if anyone has any comments!

[cart]

Excellent :)

[ItsDoot]

It might be worth taking a look at #1559 again, given its prevalence nowadays.

[SpecificProtagonist]

How would that help? Both ideally generate the same code, the difference is in how well Rust Analyzer can handle it.

[ItsDoot]

For binary size, yes they would ideally result in the same. For compile times, not necessarily.

[soqb]

fwiw PartialReflect::apply can probably be elided completely. in theory there should just be thousands of method bodies which just delegate to PartialReflect::try_apply or panic. these should all effectively be identical. i think one issue is that the apply impls for ADTs delegate to other apply impls, instead of try_apply, so all the code for panicking etc. is duplicated thousands of times, where it should just be once.

[killercup]

If we undertake this, we should have a good framework to measure the impact.
I assume we need at least before/after measurements on:

• compile time
• runtime performance
• binary size
• code clarity (subjective)

We'll also need to agree on what we value higher if any of these conflict.

Rustc has a pretty good performance dashboard to compare commits, maybe a good reference. In general, it is not easy to get consistent measurements unless someone has a dedicated machine that can be used for this (with locked cpu frequency, always same rustc version, etc. etc.). But this is a very high bar -- we can totally start without all of this.

[cart]

Yup I agree that its worth comparing each dimension. Finding the right balance will be an art, and these definitely aren't the kind of changes to merge without significant consideration and oversight.

[msvbg]

I know that a lot of people care about binary size, but from my point of view it doesn't really matter at all. Game sizes will always be dominated by assets, not code, and so I don't think it is worthwhile to spend time trying to cut down on binary size.

Compile times are much more interesting to optimize, as long as there is no cost in terms of ergonomics or performance.

[komadori]

This is true for many games, but not all. Some designs and/or aesthetics are not asset heavy.

The stripped release binary for the game I'm working on is currently ~54mb. That's nearly 7 times larger than the sum of my assets. That ratio will likely fall as I polish the game, but I think I'm on course for code size to remain the dominant factor.

[soqb]

this is also especially true for wasm (where bevy is especially popular) where size of everything matters a whole lot more than desktop/mobile.

[cart]

Its also worth calling out that binary size and compile times are often linked. Generating more code (generally) means doing more work. Obviously a complex topic, but I do think this effort in general tackles both areas.

[BD103]

As part of my bevy-bencher suite, I've been tracking the compiled file sizes of these three files with release mode, lto = "thin", and strip = true:

The file size has progressively grown, but there's no single PR responsible for a large spike. (For reference, blue is just DefaultPlugins, red is MinimalPlugins, and orange is an empty App.)

[cart]

Love this. Thanks!

[ksf]

As far as compile times are concerned the biggest speedup I got was from switching clang over to use mold, dynamic linking actually made it worse... at least with mold, it's been a while since I played around with this (and compile times have stayed snappy). Not optimising at all is also a compile time killer, presumably due to codesize exploding at the IR level if basic stuff like dead code elim doesn't run.

in cargo.toml:

[profile.dev]
opt-level = 1

[profile.dev.package."*"]
opt-level = 3

[profile.release]
opt-level = 3
strip = "debuginfo"

[profile.release-lto]
inherits = "release"
lto = true

Switch packages you're currently working on over to opt-level=1 if you want, or everything over to 3, performance difference really isn't that big. LTO OTOH really takes a while, don't put it into your edit-compile cycle it's more of a "well I'm going to ship it so it can take a couple of minutes" kind of thing. strip=debuginfo might already be the default by now, I vaguely remember reading them wanting to change it.

And in case you're on NixOS, enabling mold for nix develop (using rustc from rustup which may not be what you want) (and it seems I should bump that nixpkgs version):

flake.nix

{
  description = "bevy dev";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/23.11";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { self, nixpkgs, flake-utils }:
    let supportedSystems = [ "x86_64-linux" ];
    in flake-utils.lib.eachSystem supportedSystems (system:
      let pkgs = import nixpkgs {inherit system;};
      in {
        inherit pkgs;
        devShell = with pkgs; mkShell.override {
          stdenv = stdenvAdapters.useMoldLinker clangStdenv;   #  <---- Here be moldy magic
        } rec {
          nativeBuildInputs = [
            pkg-config
          ];
          buildInputs = [
            udev alsa-lib
            gtk3 # panic handler msgbox
            vulkan-loader
            xorg.libX11 xorg.libXcursor xorg.libXi xorg.libXrandr
            libxkbcommon wayland
          ];
          LD_LIBRARY_PATH = lib.makeLibraryPath buildInputs;
        };
      }
    );
}

[kitlith]

The annoying part about EntityWorldMut::insert_with_caller is that the bundle has to be moved, which means we can't 'just' make the non-generic portion take a function pointer (instead of a dyn/impl Fn), type erase a pointer to the bundle, and un-erase the type inside the generic portion again.

We could make the non-generic portion generic on the size of the bundle, instead of the bundle itself, and type-erase it through MaybeUninit<[u8; N]> but we might be able to avoid that by creating a type-erased reference that we can move out of.

Naive implementation, using a type-erased &mut Option

    #[inline]
    pub(crate) unsafe fn insert<T: DynamicBundle + 'static>(
        &mut self,
        entity: Entity,
        location: EntityLocation,
        bundle: T,
        insert_mode: InsertMode,
        #[cfg(feature = "track_change_detection")] caller: &'static Location<'static>,
    ) -> EntityLocation {
        // An attempt at ensuring that the types don't diverge.
        // It might be interesting to abstract this into a struct that wraps the erased type reference and the function pointer
        // more tightly, which would make it impossible for the types to diverge.
        type ErasedType<T> = Option<T>;

        fn unerase_insert<T: DynamicBundle + 'static>(
            bundle_info: &BundleInfo,
            table: &mut Table,
            sparse_sets: &mut SparseSets,
            add_bundle: &AddBundle,
            entity: Entity,
            table_row: TableRow,
            change_tick: Tick,
            bundle: erased::ErasedMut<'_>,
            insert_mode: InsertMode,
            #[cfg(feature = "track_change_detection")] caller: &'static Location<'static>,
        ) {
            // SAFETY: This is exactly the same type that we erased in the outer function,
            // and the outer function is the only one that can cause this function to be called.
            let bundle = unsafe { bundle.get::<ErasedType<T>>().take() };
            
            bundle_info.write_components(
                table,
                sparse_sets,
                add_bundle,
                add_bundle.required_components.iter(),
                entity,
                table_row,
                change_tick,
                bundle,
                insert_mode,
                #[cfg(feature = "track_change_detection")]
                caller,
            );
        }

        let bundle: ErasedType<T> = Some(bundle);
        let erased_bundle = erased::ErasedMut::new(bundle);

        // call the meat of the function
        self.insert_flat(
            entity,
            location,
            insert_mode,
            erased_bundle,
            unerase_insert::<T>,
            #[cfg(feature = "track_change_detection")]
            caller,
        )
    }
    
    // erased_flat remains almost the same, it just takes and passes through a few extra parameters
    // and accepts a function pointer instead of a `dyn FnOnce` or `impl FnOnce`

[kitlith]

I think we can remove the unsafe type erasure in my approach here by going back to the original implementation, but accepting an &mut dyn FnMut(...) instead of a Box<dyn FnOnce(...)>, and mimicking my approach of wrapping the bundle in an option that we take the bundle out of.