Introduction

Mommy's here to support you when running cargo~ ❤️

See the homepage for installation instructions~

Run whatever cargo command you would normally but add mommy after cargo~

cargo mommy check

    Checking bappy-script v0.1.3
error: expected one of `!` or `::`, found `passes`
  --> src\main.rs:20:6
   |
20 | mods passes;
   |      ^^^^^^ expected one of `!` or `::`

error: could not compile `bappy-script` (bin "bappy-script") due to previous error
mommy knows her little girl can do better~ 💞

By default mommy is kind to her little girl, but she can become anything you want~

Customizing

By default mommy is kind to her little girl, but she can become anything you want~

Roles And Pronouns

Mommy knows you might not be a "girl", and might not want her to be a "mommy" or a "her"~

Mommy will read the following environment variables to make her messages better for you~ ❤️

  • CARGO_MOMMYS_LITTLE - what to call you~ (default: "girl")
  • CARGO_MOMMYS_PRONOUNS - what pronouns mommy will use for themself~ (default: "her")
  • CARGO_MOMMYS_ROLES - what role mommy will have~ (default "mommy")
  • CARGO_MOMMYS_EMOTES - what emotes mommy will have~ (default "❤️/💖/💗/💓/💞")

See the NSFW docs for additional spicier variables~

All of these options take ISO Standard Pronoun Syntax, which is to say a slash-delimited list like "she/he/they", "girl/boy", or "daddy". Mommy will randomly select one of them whenever she talks to you~

For example, the phrase "mommy loves her little girl~ 💞" is "CARGO_MOMMYS_ROLE loves CARGO_MOMMYS_PRONOUNS little CARGO_MOMMYS_LITTLE~"

So if you set CARGO_MOMMYS_ROLES="daddy", CARGO_MOMMYS_PRONOUNS="his/their", and CARGO_MOMMYS_LITTLE="boy/pet/baby" then you might get any of

  • daddy loves their little boy~ ❤️
  • daddy loves his little pet~
  • daddy loves their little baby~ 💗

And so on~ 💓

Moods

Moods are a system for changing the flavour/vibe of mommy's messages~ 💕

Here's the moods mommy can have~

  • chill: encouragement and support from mommy~ 💕
  • ominous: mommy thinks you should prepare for the coming prophecy~ 💜

See the NSFW docs for additional spicier moods~

By default only the "chill" mood is enabled. The moods mommy can select from are chosen by the CARGO_MOMMYS_MOODS environment variable, using ISO Standard Pronoun Syntax (e.g. CARGO_MOMMYS_MOODS="chill/ominous" turns both of those moods on).

Examples: Chill

Here's some examples of mommy being chill~ ❤️ 
*pets your head*

aww, what a good girl~
mommy knew you could do it~ ❤️

that's mommy's clever little girl~ 💞

oops~! mommy loves you anyways~ 💞

do you need mommy's help~? 💓

Examples: Ominous

Here's some examples of mommy being ominous~ 💜 
What you have set in motion today will be remembered for aeons to come! 💗

mommy will see to it that her little girl's name is feared~ 💞

Ah, failure? mommy will make sure the stars are right next time

Does mommy's little girl need more time for worship~?

True Roles

While Variables like Roles And Pronouns change output, the True Role exists to change input~

TL;DR

cargo mommy i mean daddy
   mommy is now daddy~
cargo daddy check
   daddy loves you~

This feature is useful for:

  • folks who really don't want to say/see "mommy" ever again
  • folks who want to maintain several independent sets of configuration (perhaps for plural reasons)

Specifically if you change the True Role from "mommy" to e.g. "daddy", the following changes will occur:

  • You will be able to invoke it as cargo daddy
  • Instead of reading env vars like CARGO_MOMMYS_MOODS for config, it will read CARGO_DADDYS_MOODS (note the extra "S"!)
  • If CARGO_{TRUE_ROLE}S_ROLE isn't set, it will default to the True Role

The value "daddy" is arbitrary here, you can pick any value. Make yourself a cargo burger-chimes if you want!

All you have to do to change the True Role is to rename the cargo-mommy(.exe) binary to cargo-daddy(.exe).

I Mean...

As a convenience, cargo mommy i mean daddy finds the current binary and makes a copy (not a symlink or move) with the new name for you. Execution is halted immediately after seeing such an incantation, so all other input is ignored.

cargo mommy i mean mommy, or any other "idempotent i mean" is treated as sugar for "cargo mommy mommy" (which has always worked and produces 2 messages). e.g.

cargo mommy i mean mommy i mean mommy i mean mommy check
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
that's mommy's clever little girl~ 💓
*wraps you in a big hug* 💗
you did it~! ❤️
good girl~
mommy's so proud of you~

Not Just Cargo

Although Mommy is primarily intended to be invoked as cargo mommy, you can invoke her binary directly, or setup aliases to it.

If you try to make it into an alias, you should prefer pointing it to cargo-mommy directly, as this tends to play nicer with the rustup toolchain picker~ mommy will also respect CARGO to execute the right cargo for you~

REALLY Not Just Cargo

Now, this is a Developing Feature that's first shipping in 0.3.1, but...

If you want to use cargo-mommy for not-cargo programs, just set the CARGO_MOMMYS_ACTUAL environment variable to it, for example on linux you can do this:

CARGO_MOMMYS_ACTUAL=date cargo-mommy
Sun Nov 19 05:33:34 PM CET 2023
what a good girl you are~ ❤️

Enough people have been asking about this that we might end up just making a second dedicated "mommy" binary that supports this usecase more directly. We'll see~

NSFW Features

Good pet~ ❤️

All of mommy's NSFW content is hidden behind extra moods, see below~

I DONT WANT TO BE HERE

Then disable the nsfw features completely

Moods

In addition to the SFW moods, CARGO_MOMMYS_MOODS also takes these NSFW values~

  • thirsty: teasing mommy, pretty horny~ 💕
  • yikes: dommy mommy step on me, explicit sex and bdsm~ 🖤

You can enable "true mommy chaos mode" by setting CARGO_MOMMYS_MOODS="chill/ominous/thirsty/yikes", making mommy oscillate wildly between light positive affirmation, screaming about the end of days, and trying to break you in half~ 💕

Variables

The "yikes" mood also has access to the following variables~

  • CARGO_MOMMYS_PARTS - what part of mommy you should crave~ (default: "milk")
  • CARGO_MOMMYS_FUCKING - what to call mommy's pet~ (default: "slut/toy/pet/pervert/whore")

Examples: Thirsty

Here's some examples of mommy being thirsty~ ❤️ 
*tugs your leash*
that's a VERY good girl~ 💞

*smooches your forehead*
good job~

are you just keysmashing now~?
cute~ 💖

if you don't learn how to code better, mommy is going to put you in time-out~ 💓

Examples: Yikes

Here's some examples of mommy being yikes~ 🖤 
good slut~
you've earned five minutes with the buzzy wand~ 💗

*slides her finger in your mouth*
that's a good little toy~ ❤️

get on your knees and beg mommy for forgiveness you pervert~

mommy is starting to wonder if you should just give up and become her breeding stock~ 💗

Buttplug.io Support

Buttplug.io is an open-source standards and software project for controlling intimate hardware, including sex toys, fucking machines, and more.

Mommy doesn't integrate it, but she is compatible with cargo-vibe which does~ 💕

cargo mommy vibe check

Should always Just Work~ 🖤

Removing NSFW Features

By default mommy operates in a totally safe-for-work mode, where she just provides positive encouragement, but she has support for more intense experiences, and if that concerns you, you can statically compile them out with feature flags~

To get a totally safe binary, all you need to do is disable mommy's default features~

cargo install cargo-mommy --no-default-features

All nsfw strings, moods, and variables will be eliminated from the binary, leaving only encouragement~ ❤️

...and the "ominous" mood too~ 🎭

Guides

These guides are intended to help folks setup cargo-mommy in situations like these ones~

Please contribute any knowledge you have about these setups so everyone can enjoy~

Powershell (Windows)

TODO: tips on setting up persistent config for mommy when using powershell (Persistently setting values in the registry? using $env:CARGO_MOMMYS_LITTLE="boy/girl" syntax?)

https://github.com/Gankra/cargo-mommy/pull/41

Bash

TODO: tips on setting up persistent config for mommy in ~/.bashrc or ~/.profile using export and alias

https://github.com/Gankra/cargo-mommy/pull/41

Using cargo-mommy in CI

While you can of course cargo install cargo-mommy in CI, this can significantly slow down your CI runs~

To help with this, every cargo-mommy release since 0.3.0 comes with prebuilt binaries and shell/powershell installers, allowing mommy to be setup in CI quickly and easily~ 💕

See the install page for curl | sh and irm | iex expressions~

Note that if you use a Github CI Matrix and it covers Windows and Not Windows, run expressions will implicitly be a shell/powershell polyglot. If so, we recommend putting the "install cargo-mommy" expression as an argument to the Matrix (powershell on windows, shell everywhere else)~

Contributing

These are the technical rules of mommy club~

  • mommy as a project is always going to default to being mommy, and default to loving her little girl, even if she also does everything she can to be customizable for people who don't want that~ 💖
  • there is no such thing as "being too extra" about mommy, mommy is so very overengineered and that is wonderful~ 💖
  • mommy is sfw and kind first and foremost, keep the hard stuff in its corner~ 🖤
  • if you add a feature, make sure it respects mommy's True Roles~
  • mommy should try her best to make sure the underlying commands she invokes work correctly~
  • if mommy's functionality can be driven by responses.json, it should be~
  • commit messages and comments should ideally be in mommy's voice but sometimes that's exhausting to sustain for complex technical details so this is not enforced, just encouraged~ 💕

These are the social rules of mommy club~

  • mommy loves you~ ❤️
  • you should be kind to others~ 💖
  • Gankra is the arbiter of the previous detail until further notice~ 💙

For most contributions, you probably just need to edit responses.json~

See the sub-pages for details~

Concepts

At her heart, mommy exists to invoke cargo, check if the result was a success or failure, and print an appropriate message~ Printing that message involves reading a bunch of configuration from env-vars to define pools of values to randomly select from, then:

  1. randomly decide what mood the response should have
  2. use the success/failure state to select which pool of messages from that mood to use
  3. randomly select a message from that pool
  4. randomly format the message's template with any variables it uses (plus the implicit emote)

cargo-mommy has 3 major components~

  1. responses.json, where data lives
  2. build.rs, that digests that data and converts it to rust code
  3. main.rs, that handles execution

The build.rs is extremely extra, but it's actually kind of useful for making it tolerable to disable nsfw features. In theory it also makes cargo-mommy very efficient and fast, which, again, is very extra.

Responses.json

The ""schema"" of responses.json is currently the following ($SOME_VALUE here is an ~arbitrary string):

{
    "moods": {
        "$MOOD": {
            "positive": ["$GOOD_MESSAGE", ...]
            "negative": ["$BAD_MESSAGE" ...]
            "overflow": ["$E_TOO_MANY_MOMMY_MESSAGE", ...]
            "spiciness": "chill" | "thirsty" | "yikes" | <defaults to "chill">,
        }
    }
    "vars": {
        "$VAR": {
            "defaults": ["$VALUE", ...]
            "env_key": "$KEY" | <defaults to $VAR>
            "spiciness": "chill" | "thirsty" | "yikes" | <defaults to "chill">,
        }
    }
}

Moods

Moods contain pools of messages with a particular feeling/intensity. This was originally introduced to allow the user to opt into nsfw functionality. Its functionality is more general than that, and we'd be happy to have more sfw moods like "furry" or whatever.

The "chill" mood is the default mood, and is assumed to exist.

Spiciness is used to determine whether a mood's contents should be considered "nsfw" content, either "chill", "thirsty", or "yikes". Everything spicier than "chill" is considered "nsfw". There's no hard and fast rules here, just vibes. Spicier moods also gain access to spicier variables.

There are 2 moods that have the same names as their equivalent spiciness level, which may help determine how nsfw a new mood is.

Message Pools

Each mood must specify 3 pools of messages to select from:

  • "positive" messages appear when the cargo command mommy invoked was a success
  • "negative" messages appear when the cargo command mommy invoked was a failure
  • "overflow" messages appear when it was recursively invoked too many times (to break out of infinite loops from misconfiguration)

Messages

Messages are strings that optionally contain {variables} that need to be substituted (emotes don't appear in the message, they're just auto-applied to the end of every message).

Some examples:

"{role} thinks {pronoun} little {affectionate_term} earned a big hug~"

Becomes something like:

"Mommy thinks her little girl earned a big hug~ ❤️"

Messages have the following conventions:

  • {role} ends {pronoun} messages with tildes~
  • *{role} performs actions with asterisks*
  • *{role} combines both*\nwith newlines~

Variables

Variables are a pool of values that will be randomly selected from, and substituted into the templates.

The variables "mood", "emote", "pronoun", and "role" are explicitly named in cargo_mommy's main.rs, and are assumed to appear at the start of vars in that exact order.

Spiciness is used to determine whether a variable's contents should be considered "nsfw" -- either "chill", "thirsty", or "yikes". Everything spicier than "chill" is considered "nsfw". There's no hard and fast rules here, just vibes. Spicier variables should only ever be used by spicier moods.

env_key is used to define a SCREAMING_CASE env-var CARGO_{TRUE_ROLE}S_{ENV_KEY}S (note the two extra S's!). For instance the "mood" key would be CARGO_MOMMYS_MOODS.

If a variable's env-var isn't set, it will use its defaults as the pool. ("role" has no default value in responses.json because it has special logic to default to the True Role when no custom roles are set.)

If a variable's env-var is set, mommy will parse it as ISO Standard Pronoun Syntax, which is to say a slash-delimited list like "she/he/they", "girl/boy", or "daddy", and use those values as the pool.

Each time mommy encounters a variable that needs to be substituted in a message, it will randomly select a new value from the pool.

At the end of a message, mommy will randomly decide whether to include an emote.

Adding New Messages

If you want to add a new message to an existing mood, all you need to do is edit responses.json and add the string! See the concepts docs for details on the format~

That's it, no code or docs needs to be changed~ 💕

Adding A New Variable

You shouldn't need any code to add a new variable, just update responses.json and the docs~

Editing responses.json

For instance, here's a minimal example "furniture" variable that is set with CARGO_MOMMYS_FURNITURES~ 🪑

{
    "vars": {
        "furniture": {
            "defaults": ["chair", "desk"]
        },
    }
}

and here's how you might use it~

{
    "moods": {
        "chill": {
            "positive": [
                "thanks for helping build {role}'s {furniture}~"
            ],
            "negative": [
                "ouch! {role} stubbed {pronoun} toe on the {furniture}!"
            ]
        }
    }
}

That's it, no code needs to be changed~ 💕

Updating The Docs

Add the variable to the SFW variable docs or the NSFW variable docs.

Adding A New Mood

You shouldn't need any code to add a mood, just update responses.json and the docs~

Editing responses.json

For instance, here's a minimal example (SFW) "sleepy" mood~ 💤

{
    "moods": {
        "sleepy": {
            "positive": [
                "that almost makes {role} want to get out of bed...",
                "*yawns*\ngood work~"
            ],
            "negative": [
                "{role} thinks {pronoun} little {affectionate_term} might also be too tired~",
                "let's just take a nap, ok~?"
            ],
            "overflow": [
                "{role} did too much and is going to bed..."
            ]
        },
    }
}

That's it, no code needs to be changed!

Updating The Docs

Add the mood and some example outputs to the SFW mood docs or the NSFW mood docs.

Locally Building The Website

The website (and book it hosts) is automatically built for every PR, and automatically deployed for every push to main. See the releasing page for details.

If you want to run and test it locally, install oranda and run:

oranda dev

This will put oranda in a "watch" mode that live-updates the website as you edit files, while serving the result on a localhost url (usually http://127.0.0.1:7979/cargo-mommy).

Oranda internally uses mdBook as a library, with several patches to make mdbook have the same theme as the oranda one. If you're familiar with mdbook and just want to stick to that, you should be able to just go to the book/ dir and run:

mdbook serve

It just won't have the same theming as the production site.

Releasing

Mommy's release process is simple but does a lot~

Cutting a Release

  1. Checkout main
  2. pull
  3. Update the "Unreleased" section of CHANGELOG.md (DO NOT CHANGE THE HEADING!)
  4. Commit
  5. Run cargo release {version} (e.g. cargo release 1.0.0)

This will trigger this cascade of events:

  1. cargo-release will get the ball rolling:
    1. the changelog heading will be updated to "Version {version} ({date})"
    2. the version in the Cargo.toml will be update to "{version}"
    3. a commit will be made with "release: {version}"
    4. a "v{version}" git tag will be created
    5. cargo publish will be run
    6. A more robust equivalent of git push && git push --tags will run
  2. cargo-dist will see the tagged commit and build binaries/archives/installers/announcements:
    1. release.yml will spawn
    2. binaries and archives (zips/tarballs) will get built for all supported targets
    3. installers will be built that can fetch the archives
    4. A Github Release will be made, with the release notes and installers/archives
  3. oranda will see a workflow called "Release" completed, and build and deploy docs
    1. web.yml will spawn
    2. oranda will autodetect, retheme, and build the cargo-mommy mdbook
    3. oranda will generate a website with releases, the book, and a platform-autodetecting install widget for the latest release
    4. oranda will push the website to the gh-pages branch
  4. Github Pages will trigger
    1. pages-build-deployment will spawn
    2. the live website will update

Note that steps 3 and 4 trigger on all pushes to main, so updating docs doesn't require a new release~

Updating The Release Process

The cargo-release step was created by hand-copying some config values that Gankra likes to use in her projects. There shouldn't be any need to mess with it.

The cargo-dist step was created by locally running cargo dist init, selecting some targets/installers in the interactive prompts, and committing the results. It can be updated by running cargo dist init again.

The oranda step was created by running oranda generate ci, selecting some of the options, and committing the results. A custom oranda.json was then added to fix path-prefix with github-pages, and to pick a non-default theme. The CI is setup to always use the "latest" oranda, so it's self-updating and may never need to be touched. Any changes that are desired will probably be changes to oranda.json.

The Github Pages step was done in the Github Settings UI for the cargo-mommy repo. The website it deploys to is Gankra's.

Ensuring The Release Process Works

All pull requests run the cargo dist plan part of the releases ci to check that the release process still works.

All pull requests run the oranda build part of the website ci to check that the website and mdbook still works.

(This is just the default behaviour of the CI scripts that cargo-dist and oranda generate!)

Historical Releases

This process was setup for 0.3.0, everything before that was Gankra being intentionally sloppy because all of the above is her actual job and sometimes you just don't want to think about work and just want to mash cargo publish and nothing more on your shitpost that everyone took way too seriously.