A Rust library containing a collection of small well-tested primitives.

Related tags

Utilities gazebo
Overview

Gazebo - a library of Rust utilities

GitHub link crates.io version docs.rs availability Build status

This library contains a collection of well-tested utilities. Most modules stand alone, but taking a few representative examples:

  • gazebo::prelude::* is intended to be imported as such, and provides extension traits to common types. For example, it provides Vec::map which is equivalent to iter().map(f).collect::<Vec<_>>(), and str::split1 like split but which only splits once. We hope some of these functions one day make it into the Rust standard library.
  • gazebo::dupe provides the trait Dupe with the member dupe, all of which are exactly like Clone. The difference is that Dupe should not be implemented for types that reallocate or have expensive clone operations - e.g. there is Dupe for Arc and usize, but not for String and Vec. By using dupe it is easy to focus on the clone calls (which should be rare) and ignore things whose cost is minimal.
  • gazebo::cell::ARef provides a type which is either a Ref<T> or a direct reference &T, with operations that make it look like Ref -- allowing you to uniformly convert a reference into something like a Ref.
  • gazebo::any::AnyLifetime provides a trait like Any, but which does not require 'static lifetimes, at the cost of more boilerplate.

The functionality provided by Gazebo is not stable, and continues to evolve with both additions (as we find new useful features) and removals (as we find better patterns or libraries encapsulating the ideas better). While the code varies in usefulness and design quality, it is all well tested and documented.

Using Gazebo

Gazebo can be depended upon by adding gazebo to your [dependencies], using the standard Cargo patterns.

The two interesting directories in this repo are gazebo (which contains the source to Gazebo itself) and gazebo_derive (which contains support for #[derive(Dupe)] and other Gazebo traits). Usually you will directly import gazebo, but gazebo_derive is a required transitive dependency if you are sourcing the library from GitHub.

Making a release

  1. Check the GitHub Actions are green.
  2. Update CHANGELOG.md with the changes since the last release. This link can help (update to compare against the last release).
  3. Update the version numbers of the two Cargo.toml files. Bump them by 0.0.1 if there are no incompatible changes, or 0.1.0 if there are. Bump the dependency in gazebo to point at the latest gazebo_derive version.
  4. Copy the files CHANGELOG.md, the two LICENSE- files and README.md into each gazebo and gazebo_derive subdirectory.
  5. Run cargo publish --allow-dirty --dry-run, then without the --dry-run, first in gazebo_derive and then gazebo directories.
  6. Create a GitHub release with v0.X.Y, using the gazebo version as the name.

License

Gazebo is both MIT and Apache License, Version 2.0 licensed, as found in the LICENSE-MIT and LICENSE-APACHE files.

Comments
  • Adding ELI5 and Rust Nibbles to the README

    Adding ELI5 and Rust Nibbles to the README

    Summary

    Here at Meta Open Source, we've been creating short-form videos to explain Meta OSS projects in the simplest terms possible. We started embedding these videos into project pages as you can see in Docusaurus home page, Jest, Litho, Hydra, etc.

    Test plan:

    image CLA Signed 
    opened by dmitryvinn 5
  • SIGSEGV when running tests with -Zrandomize-layout due to repr(Rust) transmute

    SIGSEGV when running tests with -Zrandomize-layout due to repr(Rust) transmute

    I can product a SIGSEGV from this crate's test suite (version 0.7.1) by running

    RUSTFLAGS="-Zrandomize-layout -Zlayout-seed=1" cargo +nightly test -- --test-threads=1
    

    The --test-threads=1 just helps see which test is failing.

    The segfault occurs due to this transmute: https://github.com/facebookincubator/gazebo/blob/d85b41e081a5f94d25da723630b0b223f9997e2b/gazebo/src/cell.rs#L65 This is an attempt to transmute between two repr(Rust) types, one of which is in the standard library. This transmute is not necessarily UB, but repr(Rust) types do not have a guaranteed layout, so the current behavior of -Zrandomize-layout can swap the field order inside this crates's ARef struct, causing the fields of ARef and Ref to no longer line up as appears intended.

    FYI this is not fixable by making ARef a repr(C) struct, because the layout of std::cell::Ref is unstable too because it is repr(Rust). This instability can be observed by adding a -Zbuild-std to the cargo invocation.


    rustc 1.63.0-nightly (ec55c6130 2022-06-10)
    binary: rustc
    commit-hash: ec55c61305eaf385fc1b93ac9a78284b4d887fe5
    commit-date: 2022-06-10
    host: x86_64-unknown-linux-gnu
    release: 1.63.0-nightly
    LLVM version: 14.0.5
    
    opened by saethlin 4
  • The install instructions aren't applicable

    The install instructions aren't applicable

    The README says:

    Gazebo can be installed with the standard cargo install pattern.

    But that's only for binaries, and gazebo is a library. Shouldn't this instead talk about adding it as a dependency to Cargo.toml?

    opened by cuviper 3
  • `split1` methods use numerical values which aren't traditional in Rust naming conventions

    `split1` methods use numerical values which aren't traditional in Rust naming conventions

    Hello! Really excited to see that Facebook is contributing to the Rust ecosystem and surprised there isn't much activity here.

    If this is intentional feel free to ignore me, just browsing through the code and saw this one nit. Should the methods that split at the first index of a string use '1' in their name (e.g split1(), split1_opt()) instead of split_first() or split_start()?

    opened by eureka-cpu 2
  • docs: add social button in support of Ukraine

    docs: add social button in support of Ukraine

    Summary

    Our mission at Meta Open Source is to empower communities through open source, and we believe that it means building a welcoming and safe environment for all. As a part of this work, we are adding this banner in support for Ukraine during this crisis.

    CLA Signed 
    opened by dmitryvinn 1
  • Re-sync with internal repository

    Re-sync with internal repository

    The internal and external repositories are out of sync. This attempts to brings them back in sync by patching the GitHub repository. Please carefully review this patch. You must disable ShipIt for your project in order to merge this pull request. DO NOT IMPORT this pull request. Instead, merge it directly on GitHub using the MERGE BUTTON. Re-enable ShipIt after merging.

    CLA Signed fh:direct-merge-enabled 
    opened by facebook-github-bot 0
Releases(v0.8.1)
  • v0.8.1(Oct 18, 2022)

  • v0.8.0(Oct 18, 2022)

    0.8.0 (Jul 20, 2022)

    • Delete derive(AnyLifetime) - use derive(ProvidesStaticType) instead.
    • Add a new display module, with utilities for formatting container types.
    Source code(tar.gz)
    Source code(zip)
  • v0.7.1(Jul 20, 2022)

    0.7.1 (Jun 2, 2022)

    • Allow derive(ProvidesStaticType) to derive ProvidesStaticType (previously you had to write derive(AnyLifetime), which is still supported, but will be removed in the next version).
    Source code(tar.gz)
    Source code(zip)
  • v0.7.0(May 5, 2022)

    0.7.0 (May 5, 2022)

    • Delete MaybeEq as it wasn't that useful.
    • Deprecate split1_opt in favour of split_once introduced in Rust 1.52.0.
    • Make UnpackVariants also produce owned into_variant conversions.
    • Optimise ParitalEqAny to avoid virtual calls and heap allocation.
    Source code(tar.gz)
    Source code(zip)
  • v0.6.0(Mar 18, 2022)

    0.6.0 (Mar 18, 2022)

    • Delete any_lifetime! and any_lifetime_body! macros (no longer useful).
    • Improve UnpackVariants macro to not have a lifetime clash with 'a.
    Source code(tar.gz)
    Source code(zip)
  • v0.5.0(Feb 23, 2022)

    0.5.0 (Feb 28, 2022)

    • Delete AnyResult as it wasn't that useful.
    • Make AsARef not take self, so it must be used AsARef::as_aref(x) instead of x.as_aref().
    • Redefine AnyLifetime on top of ProvidesStaticType, allowing more types to be defined and derived better.
    • Provide AnyLifetime instances for parametric types such as Box, Vec, Result and many more from std.
    • Make Coerce derive properly with lifetimes.
    • Add .owned() extension method to any Iterator.
    • Undeprecate terminate_on_panic.
    • Update the copyright from Facebook to Meta Platforms.
    • Move to Rust edition 2021.
    Source code(tar.gz)
    Source code(zip)
  • v0.4.4(Oct 18, 2021)

  • v0.4.3(Oct 18, 2021)

  • v0.4.2(Sep 28, 2021)

    • Deprecate terminate_on_panic (use -Cpanic=abort instead).
    • Add AnyLifetime for f32 and f64.
    • Make PhantomDataInvariant::new be const.
    • Optimise the cast module.
    • Optimise string methods split1 and split1_opt.
    • Reduce reallocations in the slice/Vec extension methods try_map and into_try_map.
    • Add more assertions to coerce functions, checking invariants around compatible layout.
    Source code(tar.gz)
    Source code(zip)
  • v0.4.1(Jul 20, 2021)

    • Allow deriving Coerce of newtypes to deal with lifetimes.
    • Add copied to the prelude slice/Vec extensions.
    • Add try_unzip to the prelude Iter extensions.
    Source code(tar.gz)
    Source code(zip)
  • v0.4.0(Jul 15, 2021)

    • Breaking change: cloned and duped on the prelude Vec extensions now operate on references rather than data. For the previous uses you should use the standard to_vec() method instead.
    • Add the AsARef trait, similar to AsRef but working over both data and RefCell.
    • Extend Coerce with more instances, support for ?Sized types and a derivation.
    • Add try_map to the prelude Option extensions.
    • Add dupe_from_slice to the prelude Vec extensions.
    • Add TEq::teq_mut to convert equal mutable pointers.
    • Produce better error messages when derivations are used in inappropriate settings.
    Source code(tar.gz)
    Source code(zip)
  • v0.3.3(Jul 6, 2021)

  • v0.3.2(Jun 21, 2021)

    • Rename OptionExt to OptionRefExt (not a breaking change provided you use gazebo::prelude::*, as per the recommendation).
    • Add into_try_map for Option.
    Source code(tar.gz)
    Source code(zip)
  • v0.3.1(Jun 11, 2021)

    • Optimise the internal implementation of ARef.
    • Add ARef::filter_map, mirroring Ref::filter_map.
    • Add transmute_unchecked for transmute with less static checks.
    • Add Hashed to precompute the hash of a type.
    Source code(tar.gz)
    Source code(zip)
  • v0.3.0(May 21, 2021)

  • v0.2.2(May 10, 2021)

    • Add Dupe for most Copy types from std, namely &X, *const X, *mut X, Bound, Pin, NonNull, Poll, TypeId, PhantomPinned, Ipv4Addr, Ipv6Addr, SocketAddrV4, SocketAddrV6, ThreadId, SystemTime.
    Source code(tar.gz)
    Source code(zip)
  • v0.2.1(May 10, 2021)

    • Add Dupe for NonZero types.
    • Add an implementation of AnyLifetime for str.
    • Implement traits on ARef, specifically Display, Eq, Ord, PartialEq, PartialOrd.
    Source code(tar.gz)
    Source code(zip)
  • v0.2.0(Mar 22, 2021)

    • Breaking change: Rename clones to cloned, dupes to duped and owns to owned - to follow Rust conventions better.
    • Add Dupe for fn() (up to arity 12).
    • Add macros for chained comparison, see eq_chain! and cmp_chain!.
    • Add the OptionExt extension trait, containing duped.
    • Add the IterExt extension trait, containing try_all, try_any, try_eq_by, try_cmp_by and duped.
    • Introduce the UnpackVariants trait, to unpack the values inside an enum.
    • Allow any_lifetime!(&T) to work, and add an instance for &str.
    • Deprecate trim_start_match_opt and trim_end_match_opt. Use the functions strip_prefix and strip_suffix introduced in Rust 1.45.0.
    Source code(tar.gz)
    Source code(zip)
  • v0.1.0(Mar 22, 2021)

Owner
Meta Incubator
We work hard to contribute our work back to the web, mobile, big data, & infrastructure communities. NB: members must have two-factor auth.
Meta Incubator
Synchronization primitives for kernels.

hermit-sync hermit-sync provides synchronization primitives targeted at operating system kernels. For API documentation see the docs. License Licensed

HermitCore 5 Dec 15, 2022
Smolprng - A small PRNG library written in Rust, a translation of SmallPRNG

SmolPRNG This is a small PRNG library/framwork written in pure Rust, that is a translation of another project of mine, SmallPRNG. The main goal of thi

Dustin Kenefake 2 Jan 10, 2022
Massayo is a small proof-of-concept Rust library which removes AV/EDR hooks in a given system DLL

Massayo Massayo is a small proof-of-concept Rust library based on UnhookingPOC, which removes AV/EDR hooks in a given system DLL. I tried to reduce fi

null 53 Dec 21, 2022
Small library for text to image steganography.

hips-lib Performs text to image steganography by hinding and retrieving secret text within images or pixel arrays. This is achieved by encoding the se

hewhocopypastes 4 Feb 21, 2023
A command-line tool collection to assist development written in RUST

dtool dtool is a command-line tool collection to assist development Table of Contents Description Usage Tips Installation Description Now dtool suppor

GB 314 Dec 18, 2022
mollusc is a collection of pure-Rust libraries for parsing, interpreting, and analyzing LLVM.

mollusc is a collection of pure-Rust libraries for parsing, interpreting, and analyzing LLVM.

William Woodruff 50 Dec 2, 2022
Rust Util Collection, a simple and friendly error-chain

RUC Rust Util Collection, a simple and friendly error-chain, with many useful utils as an addition. The painful experience of using error-chain gave b

漢 8 Dec 8, 2022
Rust Util Collection, a simple and friendly error-chain, with many useful utils as an addition.

RUC Rust Util Collection, a simple and friendly error-chain, with many useful utils as an addition. The painful experience of using error-chain gave b

漢 6 Mar 27, 2022
Crate of GitHub’s collection of gitignores, embedded, automatically updated

Gitignores GitHub’s collection of gitignores, embedded, automatically updated. API documentation. Public Domain via CC0-1.0 (same as source data). MSR

null 3 May 3, 2022
Artifact collection tool for *nix systems

fennec is an artifact collection tool written in Rust to be used during incident response on *nix based systems. fennec allows you to write a configuration file that contains how to collect artifacts.

AbdulRhman Alfaifi 147 Dec 19, 2022
A collection of functions written in Triton VM assembly (tasm)

tasm-lib This repository contains a collection of functions written in Triton VM assembly (tasm). There are two big projects to be written in tasm: Th

Triton VM 2 Dec 20, 2022
lipsum-cli is a small terminal application written in Rust language.

lipsum-cli is a small terminal application written in Rust language. It's used for generating pseudo-Latin lorem ipsum filler text in terminal.

Civan Yavuzşen 5 Nov 28, 2022
A small utility for tracking the change in opening and closing of issues in a GitHub repo

A small utility for tracking the change in opening and closing of issues in a GitHub repo. This tool can be used to build visualizations for issue triage over time with the hope of motivating closing more issues than are opened.

Ryan Levick 12 Sep 29, 2021
A small tool to clone git repositories to a standard location, organised by domain name and path.

A small tool to clone git repositories to a standard location, organised by domain name and path. Runs on BSD, Linux, macOS, Windows, and more.

Wesley Moore 68 Dec 19, 2022
💫 Small microservice to handle state changes of Kubernetes pods and post them to Instatus or Statuspages

?? Kanata Small microservice to handle state changes of Kubernetes pods and post to Instatus ?? Why? I don't really want to implement and repeat code

Noel ʕ •ᴥ•ʔ 4 Mar 4, 2022
This is a small demo to accompany the Tauri + Yew tutorial

Tauri + Yew Demo This is a small demo to accompany the Tauri + Yew tutorial

Steve Pryde 94 Jan 2, 2023
Small utility to display hour in a binary format on the Novation's Launchpad X.

lpx-binary-clock Small utility to display hour in a binary format on the Novation's Launchpad X. Hours, minutes and seconds are displayed one digit pe

Alexis LOUIS 1 Feb 13, 2022
🦀 Small Tauri SolidJS Example feat. Vite

Tauri Solid Example (2022) Simple Solid(vite) starter running with Tauri. Should hopefully save some time trying to setup Tauri and Solid. Currently c

Luke Secomb 14 Oct 25, 2022
A library to compile USDT probes into a Rust library

sonde sonde is a library to compile USDT probes into a Rust library, and to generate a friendly Rust idiomatic API around it. Userland Statically Defi

Ivan Enderlin 40 Jan 7, 2023