A new aircraft does not get cleared to fly because its blueprint is internally consistent. It gets cleared because someone strapped it to a rig, ran it through scripted abuse, instrumented every joint, and — after hours and hours of tests — produced evidence that the design survives a controlled approximation of the real world. That ritual has a name in aerospace and motorsport — shakedown — and it exists because the cost of guessing is paid in catastrophic failures, irreparable damage to human lives, and the heavy material losses that follow.

Software shipped to production has the same shape of decision and almost none of the same ritual. We tag, we deploy, we wait. Go or no-go.

Here is an uncomfortable observation. As an industry, we automated the cheap half of trust. Types check. Schemas validate. Contracts get signed off in OpenAPI. Unit tests are green. Coverage is up and to the right. Every one of those is a statement about the symbolic world of the codebase — the world where our abstractions agree with each other. And that world is, by construction, the world that is easy to automatically certify for correctness.

Symbols can sprawl into endless glosses; evidence stays finite — the same map-versus-ground tension as in The Relative Trap. Here the focus is narrower: what we automated in the pipeline, and what still has to meet reality on go/no-go.

The expensive half — proving the system behaves the way we intend when wired to real infrastructure, real sequences, real faults, real timing — we still answer with a vibe.

We answer it in war rooms after the fact.

We answer it with a senior engineer who has “a feeling” about the merge.

We answer it with a staging environment that nobody fully trusts, and a rollback plan we hope we don’t have to use.

That’s what we compensate for by not deploying on Fridays.

The lesson is narrower and harder than “test more.”

That mission control go/no-go answer belongs to a category of decision the toolchain has not earned the right to make yet.

Pipelines today can tell you the code is consistent with itself. They cannot tell you, with reproducible evidence, that the system survives the part of reality you actually care about — the broker that stalls, the migration that races the seed, the consumer that lags, the dependency that flaps.

Until that evidence is as cheap to collect as a unit test is to write, we will keep calling faith “rigor” and paying the difference in incidents, postmortems, and quietly eroded customer trust.

The next leverage point in CI is not faster tests or smarter linters or another contract format. It is realistic tests — scripted, repeatable, instrumented, boring to run — that turn “I think we’re safe to ship” into an artifact a regulator, a teammate, or a future-you can replay. The teams that close that gap will stop arguing about whether AI wrote the code or a human did, because the question will have moved. The question will be: show me the evidence.

Right now, for most teams, the honest answer is that there isn’t any.

That is the gap.

We’ve all heard the warning: “Every extra function call adds overhead. Inline it!” In Rust async code, that worry is almost always false.

Look at the size of that arm:

async fn handle_event(&self, event: Event) -> Result<()> {
    match event.kind {
        EventKind::Suspend => {
            // … > 20 lines of app behavior … 
            }
        // … other arms …
    }
}

The author had hot context in his head when he wrote it and now you’ll see his bias to justify it. And make others justify it too — expecting teammates, contributors, and his future self to accept the cost: lost readability and maintainability. All to satisfy that hot context for no concrete win once it goes cold.

Since the Suspend arm has grown beyond a handful of lines, someone proposes extracting it. You get a clean call site and the logic in a named function:

async fn handle_event(&self, event: Event) -> Result<()> {
    match event.kind {
        EventKind::Suspend => self.handle_suspend(event).await,
        // … other arms …
    }
}

async fn handle_suspend(&self, event: Event) -> Result<()> {
    // … > 20 lines of app behavior …
}

Then someone on the team raises an eyebrow. “Isn’t that an extra function call? Indirection has a cost.” Another member quickly nods.

They’re not wrong in principle. But are they right in practice?

What’s the compiler’s opinion on this? Let’s think through it carefully and measure it.

First, the technically correct abstract concern: extracting code into an async function means:

• Parameter passing and ABI compliance.
• Runtime future state machine setup (e.g. pointing to a created state, similar to a jump table).
• Pinning a self reference (needed when borrowing across awaits).
• Pushing and popping a stack frame — with adequate pointer nailing.
• Extra runtime indirections for scheduling queues, wakers, and the event loop.

These are all things that exist. The question is whether they matter relative to everything else going on.

In our snippet, the Suspend arm does what handle_suspend does; the match is already a branch. A match on an enum compiles to a jump table or a chain of comparisons. You’ve already paid for a branch. Adding a function call inside one arm adds roughly one more indirect jump and frame setup — that’s noise compared to whatever actual work Suspend is supposed to do.

When you await an async function, the compiler doesn’t necessarily allocate a new object on the heap or introduce dynamic dispatch (you’d rarely Box the future). What happens is that it merges the callee’s state into the parent Future’s state machine. That can make the abstraction genuinely free: your async future gets flattened into the callee’s state machine. The extra await point you’re worried about may compile down to the same state transitions the inline version would have produced anyway.

Are you letting the wrong details dominate code design?

What you are actually trying to get your system to achieve is what influences execution the most. If the Suspend path involves I/O, a lock, or any kind of allocation, you’re measuring nanosecond noise against microsecond signal. A function call boundary is on the order of a few cycles. A syscall is thousands. Don’t treat them as the same kind of cost. You know these don’t belong in the same conversation.

In release mode, with optimizations enabled, the compiler will often inline small extracted functions automatically. The two versions — inline and extracted — can produce identical assembly.

You can check this yourself.

/// Work done entirely inside this function (no extra call).
#[no_mangle]
fn do_the_work_inlined() -> u64 {
    let mut acc = 0u64;
    for i in 1..=10 {
        acc = acc.wrapping_mul(i).wrapping_add(12345);
    }
    acc
}

/// Same work, but behind an extracted helper (one extra function call).
#[no_mangle]
fn do_the_work_extracted() -> u64 {
    do_some_work()
}

#[no_mangle]
fn do_some_work() -> u64 {
    let mut acc = 0u64;
    for i in 1..=10 {
        acc = acc.wrapping_mul(i).wrapping_add(12345);
    }
    acc
}

Emit assembly locally:

cargo rustc --release -- --emit asm

And look at the output (it will be an asm .s file in target/release/deps). If the assembly of do_the_work_inlined and do_the_work_extracted is the same, the debate is over before it started.

Folks are arguing about a distinction that doesn’t survive compilation.

Now the thesis is clear: Indirection is not the enemy of performance — it’s a misconception that makes engineers chase invisible gains.

For completeness let’s acquire a sense of dimension and see what numbers we get experimentally.

cargo bench

Criterion will give you mean execution times and confidence intervals. If the error bars overlap, the difference is not real and the team would be letting their discussion be dominated by noise.

If you need to take a performance regression seriously in that situation, we need to remember that microbenchmarks can mislead. For a more honest picture, run your actual application under a profiler:

• valgrind --tool=callgrind
• perf record or perf report, or flamegraph
• dtrace or Instruments (Time Profiler) on macOS

Look at where time is actually being spent. If handle_suspend doesn’t appear as a hotspot — or appears but at a fraction of a percent — the conversation is over.

When indirection actually matters?

There are cases where call overhead is worth thinking about:

• Tight inner loops — a function called millions of times per second in a tight loop, where cache pressure and branch prediction genuinely matter.
• dyn Trait — dynamic dispatch is a real indirection: a vtable lookup that the compiler cannot inline through.
• Explicit indirection in performance-critical paths — same idea: the compiler loses visibility and can’t optimize across the boundary.

All cases where you are in a CPU intensive blocking task that, if you’re not careful, could starve all the others.

But none of these apply to a match arm in an async function that handles discrete events. If your Suspend arm ran ten million times per second in a tight loop, you’d have other things to worry about first.

Be honest: are you really building a systems-level program where micro-optimizations have weight, or an application where system-level behavior dominates? Sometimes the problem we’re optimizing for isn’t even stable yet.

Then what about the cost that isn’t paid at runtime?

That the measurement doesn’t show up in a profiler doesn’t mean it’s any less real. These human-centric costs compound over time and outweigh wildly a few nanoseconds of execution.

Every developer who opens that function pays a comprehension tax.

Cognitive load isn’t free. Every code review takes longer. Every future change carries a higher risk of introducing a bug because the context is harder to hold in your head. These costs compound over months in a way that a few nanoseconds of function call overhead never will.

And what about the next lines of code that will be added there? Will it make understanding the rules and system behavior ramifications easier or harder in that Suspend arm?

Rust’s design philosophy is explicit about this: write clean abstractions, trust the optimizer, and reach for #[inline] or #[inline(always)] only when you have measured a real problem and have no better option.

This is what good engineering is about.

In practice, the extra call cost is zero in release builds and most times statistically insignificant. The real cost of removing indirection is the lost clarity, testability, and developer productivity that you pay for a handful of nanoseconds justified with transient personal convenience.

So next time someone asks whether to inline or extract, answer with the numbers from your release benchmark and remind them that performance wins are measured in seconds of I/O, not in a single call. Keep your code readable; let the compiler handle the rest.

Besides, is your system reaction to that event even unit testable? How do you test it clearly without one method that encapsulates that behavior?

Extract the darn function. Name it well. Provide meaning to it. You do that and now you have a place to add a comment about the rules that apply when your system needs to react to that case. The most valuable comments are those that help you understand system behavior fast.

And if you’re worried, then measure; if a profiler ever tells you that a specific call is a bottleneck, you’ll have the data to justify the tradeoff. Until then, optimize for the people reading the code. That includes you when you need to own how it works. And by the way, the AI agents will benefit from that as much or even more.

Maintainability and understandability only show up when you’re deliberate about them. Extracting meaning into well-named functions is how you practice that. Code aesthetics are a feature and they affect team and agentic coding performance, just not the kind you measure in the runtime.

And be warned: some will resist this and surrender to the convenience of their current mental context, betting they’ll “remember” how they did it. Time will make that bet age badly. It’s 2026 — other AI agents are already in execution loops, disciplined to code better than that.

And when executing coding becomes radically cheap, how do you think your system behavior is driven? What’s the weight of understanding system behavior quickly in this new coding economy?

So I don’t know you, but you’ll never see me sacrificing meaning on the altar of “winning one less indirection.”

You know the moment: someone writes the problem on the board. Someone else refines a word. A third adds a constraint. Then — silence and nods. The problem is defined.You can build from here. It feels solid.

Protecting that feeling and keeping it unchallenged is the trap.

We mistake agreement for stability.

A shared problem statement feels like progress because it gives the room something to hold. Long-term bets need an anchor — so we lock the problem in and call it stable. But we didn’t stress-test it.

We didn’t wait for the second day, the forgotten stakeholder, the edge case that reframes everything.

Our intellectual surface didn’t expand enough; we forgot to listen to other voices soon enough, and their perceptions didn’t have a chance to shape our design.

The problem we agreed on was the first draft.

We treated it like the final one.

You like to code — maybe too much — and it distracts you from the true intent: the problem that’s trying to be understood before you build over it. How strong are you to refrain from jumping into coding too soon? Are you protected from yourself?

Why does that happen? Three things. We confirm what we already believe and ignore what doesn’t fit. We freeze on the first clear formulation — the one that seemed obvious in hour one — and miss the messier layers underneath. And we overtrust the neat statement: it feels like work done, so we stop questioning it.

The result is architecture that fits the story we told ourselves in that meeting, not the story the world will tell us later. When new information arrives — and it always does — the design cracks. Not because the solution was wrong, but because it correctly solved the wrong problem.

It wasn’t stable enough.

Don’t start building when everyone nods. Start when the problem has survived a deliberate attack. Pause after the first formulation. Ask: What would break this? Who isn’t in the room? What do we assume about the environment that might change? How does it honour history? — backward compatibility. How is it friendly to the future? — flexible for behavioural extensibility.

Give yourself a chance to design how the problem is seen.

You don’t need scope creep to avoid falling into the relative trap.

Revisit the problem after each round of thinking — peel layers until what remains has actually been challenged. When the problem is properly bounded, the rules of your design become explainable.

Feed it with real input: second-day insights, colleagues who see different angles, usage and constraints that show up only later. Treat the problem as a living thing that gets revised, not a box you close on day one. True stability isn’t the absence of doubt. It’s what’s left after doubt has done its work.

When the problem itself is still unstable, precision is theatre. The discipline is simple: keep questioning. Stay open to new input. Only commit when the problem gives you reality today, good history, and a design friendly to new rules tomorrow. When design is the new programming, that discipline is where leverage lives.

The best problem statement in the room is not the one everyone agreed on first. It’s the one that generated the solution that survives when the real world tries to punch it in the face.

Most companies have a mission. Almost none have a manifesto. Branding is not enough.

A mission tells people what you do. It’s operational — “We build X,” “We help Y achieve Z.” Useful. 99% relevant to contributors and team leaders, and 1% relevant to the curious.

But what about the public?

For them a mission is easy to forget because your mission is not their mission.

A manifesto is different. It’s a public promise: who you are, why you exist, and what you will and won’t do while you’re doing it. Most teams have the first. Few have the second. So when chaos hits — a tempting deal, a pushy client, a cost cut — there’s no filter. Decisions follow mood, pressure, or the last person in the room. The mission doesn’t help, because it never promised anything. It only described activity.

The mission is an operations guide. A manifesto is fuel.

The manifesto is where are we going? The mission is how do we get there? Different levels of attention.

The manifesto is poetic, emotional, the thing that makes you wake up with fire. The mission is practical, measurable, sometimes dull — the daily grind that fulfills the promise.

If you only have a manifesto, you dream and don’t deliver. If you only have a mission, you operate like a soulless robot. When you have both and they’re aligned, you have something rare: a business that knows what it stands for and actually does it.

This enables people paying attention to track your reputation beyond stock price or a balance sheet: they can track your story beyond your current offers.

“It all begins with …”

Inception happens when your promise nurtures people’s imagination. They cannot articulate how to continue that story easily by themselves. The manifesto makes it easier for them to talk about you.

“Promise” is the lever. When you say out loud — to your team, your clients, the world — “In this company we never sell crap disguised as premium,” that sentence becomes a standard you can explain.

People use it to reject projects, to defend values, to hire and fire. But also to justify why they “hired” your product. It becomes culture because it helps them make progress. A mission statement doesn’t do that. It describes. A manifesto commits.

And that commitment creates accountability.

You can’t hide behind “we’re a growth company” when your manifesto says you don’t sacrifice quality for scale. The promise is the contract.

But hold on, isn’t that just branding?

No. Branding is how you want to be seen. The desire for an outcome. A manifesto is what you’re willing to be held to.

It’s a decision.

This decision functions as a filter — “Does this fit what we promised?” — and a moral contract. When money is tight or a shady opportunity appears, the manifesto is the compass.

Many businesses fail not because they lacked strategy, but because they never clearly defined their boundaries and their promises. The manifesto protects you from yourself. It also attracts the right clients and talent and repels the rest. People who don’t fit leave on their own. That’s not branding. That’s structure.

Once you have clarity on when you’re talking to your team of leaders and when you’re talking to your clients, the question isn’t “What’s your mission?” The question is: What did you promise, and did you keep it?

If you can’t answer the first part, you don’t have a manifesto. Drafting an improvised one on the spot doesn’t show respect for a long-term commitment. Write the promise. Then build the mission to fulfill it.

The manifesto is the fire. The mission is the engine.

Most companies only have the engine. No wonder so many of them run hot and go nowhere.

Fortran. Lisp. C. Smalltalk. Ruby. Rust.

Seventy years of increasingly powerful languages, each one turning the previous generation’s hard problems into routine. Then, somewhere around 2025, the list took a turn nobody on it anticipated.

English.

Well, natural language.

Not a syntax. Not a virtual machine. Not a paradigm. Not even a formal language. Just what you’d say to a colleague. AI transpiles your intent into source code so compilers can translate it to machine instructions. The exclusive discipline that required mastering at least one programming language? Over. The bottleneck that kept most people from building software? Dissolved.

An MVP, coded in a week. Senior-level architecture. Maybe not production-grade, but demo-ready — and from there you can go places. Any language you want. It’s not fiction anymore.

So now what?

This isn’t just happening to code.

Architecture is design for buildings. A craftsman making high-fashion shoes is a designer for footwear. A typographer designs reading experiences. A novelist designs characters and their stories.

The heavy lifting of execution is being disrupted everywhere. Not just in software. Across every discipline where “making the thing” used to be the hard part.

When the making gets cheap, what’s left?

What’s left is the filters that let you express intent when building something. Having the discernment of what to build and why.

What’s left is design.

Not design as “make it pretty.” Design as the discipline of shaping how something works, how it’s experienced, how it communicates intent before a single word is read or a single button is pressed.

But not just product shaping either. Design as the process behind the product. How the paths for its growth get their friction removed. When we think strategy, we are designing a route. Steering. Shaping a journey.

If execution is now 90% handled (or choose your number) the question isn’t “can I build it?” It’s “do I know what to build and why this shape?”

How to answer that? With an evasive maneuver — a short-term win that saves the day — or a frontal, long-term adaptive answer?

Place your bet.

Here is one: Own it.

Be the factory owner. Own the attention that used to go to execution by owning the process of how your product is shaped, how it shapes its audience’s experiences, and how it reaches them.

Fill it with what makes a remarkable product for its given people. Finding them means you found the commonalities, and detecting those patterns means you’re sensitive to good design.

Here is where most technical people quietly fail.

Lack of proportion: not helping the user navigate their journey.

Poor contrast: you fail to communicate what’s important the moment it sits next to something else.

Poor balance or missed alignments: you reveal kindergarten-level design thinking.

Unclear hierarchy: your proposals feel dumb or unintelligible.

Lack of unity: your entire promise is weak and insubstantial.

Disregarded patterns: you’re just another one who shipped something “almost good enough.”

These aren’t aesthetic preferences. They’re structural failures. The same way a buffer overflow or a race condition is in code, except they live in the layer your users actually touch.

You can prompt an AI to produce senior-level internal software architecture. You cannot prompt your way into understanding why your product feels wrong to hold.

Every product has a designer who expressed intent when shaping it. Every user experiencing that shape receives a force of progress or of friction. That symbolization process is happening whether you designed it deliberately or by neglect.

The factory is yours now. AI put the machines, the materials, and the labor in the hands of anyone willing to use them.

But a factory without someone who understands processes, proportion, contrast, balance, hierarchy, unity, and patterns isn’t a factory. It’s a warehouse full of parts nobody wants to assemble.

People notice fast when the job is incomplete.

Keep ignoring that you shape every level and you’re removing yourself from the possibility of being a builder. You’ll own the machines but not know what they should make — or for whom — or why anyone should care.

Once natural language is the new programming language, design is the new programming language.

Program well.

The default today is simple: AI is good. Prompt it. Ship the result.

It’s seductive. The model returns something usable — sometimes remarkable. You didn’t have to think hard about the problem. You didn’t have to break it down. You just asked and received. So you keep doing it. Prompt, accept, ship.

That’s not “using AI well.” That’s outsourcing control.

Here’s the uncomfortable part: the system got better at understanding and solving the problem, but you don’t know how.

You can’t walk through the layers. You can’t point to where the nuance was captured or where the devil was kept out. You can’t explain with precision how the solution ties back to the problem.

The intelligence improved; your grasp of it didn’t. You’re fine with all of that control living inside one platform — then what do you actually own?

The same thing can happen with a team. A business owner has clever people; they resolve the challenge and he doesn’t really know how.

The difference: he can have them walk through, examine and scrutinize each layer and how it fits the problem. They “own it”; they can teach him any detail. Together they are in control.

With AI? Not so much. You don’t get the walkthrough unless you intentionally build it.

Worst part? You can’t tell how safe each layer really is. You can’t be as confident — and that hurts your whole brand narrative. You can’t be deterministic about outcomes. Clarity on the mission blurs. The promises in your manifesto weaken. So what’s left for people to believe in? You’re left with breadcrumbs and pretending. You want to sell something of substance or hype?

Using AI well doesn’t mean just “get great output.” It means you own the process that produces the output.

It means that you don’t get passionate about your solutions so fast.

It means you love the problem more — and people in pain can find comfort in you. It means you are leveling up your maturity to select your creativity.

Your intention finds a channel of expression when you become deliberate.

When you put the process before solution you design how the problem is seen. You decompose it into smaller problems that can be fixed one at a time. You add the layers of decomposition that capture the nuances that would otherwise be the details where the devil gets in.

In the same way a business owner selects and trains his team members, you train or configure agents, add domain knowledge, and add feedback loops so the output is curated to your taste and your technical judgment and your vision of the world.

The alternative to “prompt and ship” isn’t “don’t use AI” or keep prompting more, making you a per-project micromanagement bottleneck.

The alternative is: own the curation of the process that leads to something remarkable. The heavy lifting isn’t a problem anymore. You define the steps; the models collaborate to fill them.

You are the factory now.

You have the opportunity to use AI to amplify you. You know how the problem was framed, how it was broken down, and how the result was checked. You know how to scrutinize each quality gate and how your solution is architected.

That’s what you own.

Your process is either in control or you’re a tenant in your own factory.

You pushed the code. The tests are green. The feature is live.

And three days later, the audience finds out by accident.

This happens more often than anyone admits. Not because people don’t care — but because creation and delivery run on fundamentally different fuels. And the tank is empty by the time delivery starts to matter.

The builder’s trance

Development is a deep act of creation. You enter the loop: write, test, break, fix, refine. The happy path takes shape. Then the exceptions. Then the edge cases that only reveal themselves when you slow down and think in adversarial mode.

All looking good.

You’re setting your workflow and your rules. Can you state them clearly? Do they hold under pressure? Under malformed state? Under the load nobody warned you about?

This phase demands total immersion. It rewards tunnel vision. The world outside the problem shrinks to nothing, and it should — because that focus is what makes the solution good. You are deep in your exciting technical journey, intermediary progress compounding, QA passing one scenario at a time.

And a good builder has good reason to stay there. That deep thinking is what lets you model the reality, not the patterns — to see the domain clearly enough to let the right abstractions emerge instead of forcing the wrong ones. It’s also what keeps you from falling into the relative trap, where everything becomes an infinite loop of interpretation keeping you in analysis paralysis. The trance isn’t indulgence. It’s how you cut through noise to reach the signal.

The builder’s trance is sacred. It’s how real things get made.

But that trance has a cost that too often is overlooked.

Three games, three fuels

Development demands creation focus. The iteration loop. Happy path, exception handling, rule enforcement. Does this abstraction hold? Does that boundary leak? Can I explain why this works? This is generative energy — the kind that builds things from nothing.

Release demands closure focus. A completely different animal. You’re no longer asking “what should this do?” — you’re asking “will this survive?” Can we play this new game confidently? In all circumstances? Under all expected loads? The rules you’ve built need to be in full force, ready to become the new environment. Closure is not creativity — it’s conviction. A different muscle, a different anxiety.

Landing demands a different focus entirely. Not “is it done?” but “how does the rest of the world find out — and yield this properly?” Whether it’s a teammate, an organizer, or you switching hats — someone needs to orchestrate communication, set expectations, coordinate the rollout, make the feature matter to people who never saw the code. That someone is responsible for starting the story that makes this exciting for everyone else.

That story can’t be told if nobody — including you — acknowledged the chapter is written.

The expert’s blind spot

Here is the brutal truth: the person who built the thing is the worst person to remember the handoff.

Not because they’re careless. Because they’re spent.

Creation is expensive. The developer has been context-switching between “how should this work” and “what happens when it doesn’t” for days or weeks. When the last test passes, when the deploy succeeds, the brain doesn’t celebrate — it collapses. Relief feels like completion. And a personal context refresh was well earned.

But deployed isn’t delivered.

The deploy is the end of the building. Delivery is when someone — a teammate, your audience, or the next version of yourself — can carry it forward. That notification, the one that feels trivial, the one you’ll “do in a minute” — is the bridge between a feature that exists and a feature that matters. Skip it, and your work sits in production like a gift nobody opened.

Cost of Delay and Time Value of Money weren’t concepts created because of nothing. Ignore them and you’ll be missing out on compounding returns on early capital that might never come back.

It is brutally easy for an expert to be exhausted at the finish line and forget that the finish line isn’t theirs. It belongs to the person waiting on the other side.

Creation, closure, and landing are three different games with three different rules. The mistake is treating them as one continuous flow because they feel sequential. They aren’t. Each demands a different kind of attention, a different energy, a different definition of “done.”

The expert’s blind spot isn’t incompetence. It’s exhaustion masquerading as completion.

If you build something and don’t hand it off, you didn’t ship — you just deployed.

And deployed isn’t delivered — so it can’t lead.

The last act of building isn’t the final commit. It’s what lets the work lead somewhere.

It’s the message that says: “It’s ready. Your turn.”

Every abstraction you introduce is a set of rules in disguise. A class, a module, a function, a service boundary — each one silently declares: here’s what you can do, here’s what you can’t, and here’s why.

The sign of a mature design is that you can explain those rules in a sentence or two. Not because the problem is simple — but because the solution has been distilled to its essence.

Try it. Pick any structure you’ve recently introduced. Explain its rules to a colleague in plain language. If the explanation is short and clear, you’ve likely arrived at a good design.

If you can’t — if the explanation sprawls, if it requires caveats upon caveats, if the listener’s eyes glaze over — that’s not a communication problem. That’s a design problem.

And it usually means one of three things happened.

A hacky solution was implemented

The rules are hard to explain because they aren’t real rules — they’re side effects of a shortcut. “Well, you can’t call this before that, because internally we’re reusing a buffer that gets initialized on the first call, and if you…” — stop. That’s not a rule. That’s an implementation leak dressed as a contract.

Hacks produce temporal rules: order dependencies, initialization sequences, hidden state mutations. These rules feel complicated to explain because they don’t model anything real. They model the path of least resistance someone took at 11 PM on a Friday. The nest of accidental complexity.

A rule that needs three paragraphs to explain is a rule that will be problematic. It’s only a matter of time. It will create friction in the wrong places, it will stop enabling you to grow when you’ll need it most.

A can of worms was accepted

Sometimes the rules are hard to explain because the problem space was never properly bounded. You accepted a requirement that seemed small but carried exponential accidental complexity beneath the surface. Now your abstraction has seventeen configuration options, four modes, and a matrix of valid combinations that A) nobody can hold in their head B) are failing to capture the spirit of the narrative of the UX they are supposed to produce.

The rules are complicated because the scope was never challenged or the abstractions are drafty, immature. Good design can have essential complexity, but that demands time, deep thinking, and maturing how the abstractions make the narrative flow. “Can it also handle…?” was answered with “sure” too many times, too soon, in too unconsequentialist a fashion — and now you have a half-working Swiss Army knife that can shoot you in the foot in a combinatorial explosion of seventeen parameters. Functional elegance went down the drain.

When you can’t explain the rules, ask yourself: did I accept complexity I should have refused?

Did I think about them in slow motion, deep enough? Enough times? When did I give the universe a chance to inspire me about the edge cases and subtleties around its dynamic behavior? Under heavy load? Under malformed state?

Saying no to a requirement is sometimes the most important design decision you’ll make.

An elegant design was rejected

This is the most painful one. Sometimes a clean, simple design existed — one where the rules would have been self-evident — but it was rejected. Too “academic.” Too much refactoring. Too risky to change the existing structure. Too expensive for this sprint.

The right structure wanted to exist but nobody gave it a chance.

So you bolted the new behavior onto the old structure, and now the rules are a patchwork of the original intent and the compromises that followed. The explanation is long because you’re narrating a history of decisions, not describing a coherent design that implemented a coherent story. Technicisms hijacked the UX story — and injected friction into the users’ and operators’ journeys.

Every time you explain rules by telling a story — “well, originally this was X, but then we needed Y, so now Z” — you’re confessing that the design was never unified. You aren’t stating rules. You’re reciting scars.

These three failure modes look different on the surface, but they share a root cause: the design was allowed to grow around the problem instead of through it.

The problem didn’t get the love it desperately needed.

The solution got too much emotional attachment too soon.

Rules are the interface between your design and everyone who will ever use it. Including future you. Including the AI that will generate code against it next month. If those rules are simple, your design can be extended, tested, and reasoned about. If they’re complex, every future change carries compounding risk that remains silent until something breaks.

Mature design doesn’t mean fewer features. It means the features that exist have rules so clear they barely need documentation because they feel natural for the users’ journeys.

The question isn’t whether your code works.

The question is: can you explain its rules?

Can you take good care of them long term?

If you can’t, you already know what to fix — you just need to exercise the muscle of expressing it.

Creatives, product developers, and most entrepreneurs believe that if their product is good enough, people will simply buy it. They work themselves to the bone adding features, lowering prices, or polishing the interface, only to watch their business die in the desert of indifference.

The reality is harsher: you can have the best product in the world and still lose to nothing.

You aren’t competing against your direct rival. You aren’t fighting the sharks in the “red ocean” you intentionally sought to avoid. You are competing against fear, laziness, and the “we’ve always done it this way” mentality.

These forces might not feel material, but if you don’t understand the physics of change, you aren’t marketing a product—you’re just shouting at a wall. Or a mountain whose mass you haven’t correctly calculated.

Bob Moesta and Clayton Christensen gave us a useful lens: human progress as a balance of four force vectors.

(Push + Pull) > (Anxiety + Inertia)

Calculate accordingly.

Once that clicks, you start doing napkin math on every human interaction — and you stop guessing why people don’t move. You understand where to find signals, what questions to ask, how to pull new details to expand your understanding of the dynamics at play.

For someone to “hire” your solution, the forces of movement must outweigh the forces of resistance:

The Accelerator (Driving the change)

1. The Push (Repulsion): The kinetic energy of current pain.

• Example: You don’t switch your accounting firm because of a “nicer logo.” You switch because they missed a tax deadline and the government just sent you a fine. That’s a heck of a strong repulsive force.

2. The Pull (Magnetism): The gravity of a better life.

• Example: It’s not about “new software.” It’s the vision of finally leaving the office at 5:00 PM because your workflow is actually automated, instead of spending your Sunday nights in a spreadsheet.

The Brake (Holding them back)

3. The Anxiety (Uncertainty): The “handbrake” of the unknown.

• Example: The fear that “moving my data might corrupt the files.” Even if the new tool is better, the fear of a 1% catastrophic error keeps people paralyzed.

4. The Inertia (Current Habits): The comfort of the “devil you know.”

• Example: Using a clunky CRM because “everyone already knows the keyboard shortcuts.” Habit has a gravity that rewards staying in a mediocre situation.

The Engineered Progress

Progress isn’t a matter of desire; it’s a balance of power in a given direction. They’re feeling your product like a signpost were you are calling for attention and saying: “Hey guys! Here! Let’s go this way.”

It is a fundamental mistake to focus solely on Attraction. Is good to have as much as you can it but is not their final destination. Also a “nice pull” is useless if it is completely overwhelmed by an unaddressed Anxiety or the undetected force of Current Habits. You are asking your product’s value proposition to do work it realistically cannot do.

Desire validates attraction, but the resistance of comfort neutralizes initiative.

Facilitating change must be intentional, designed, and built. That often means the logistics of removing every stone from your customer’s road before they even try to reach yours. People don’t buy a product; they buy an improved version of themselves.

You are either the optimizer of that progress, or you are invisible.

If your customer feels the pain of missing opportunities but is paralyzed by fear, your job isn’t to sell them more features. Your job is to dissolve their fear, break their routine, and prove that the danger of remaining stagnant is far greater than the risk of moving forward.

You can surrender to your current habits, but your product will keep loosing to inertia.

Stop trying to accelerate while stepping on the brake.

We’ve been sold the idea that everything is relative. That your reality and mine are parallel bubbles, and that every symbol is an infinite well of interpretations. It sounds inclusive. It sounds intellectual. But it’s a trap.

This trap creates an illusion of progress. Inside, you are sprinting through an infinite loop of meaning; outside, you are frozen. You are busy, but you aren’t moving.

The problem is that while symbols are polysemous and they can have too many interpretations, evidence is finite. You can debate the meaning of a map forever, but if the map shows a cliff and you keep walking, gravity won’t pause to interpret your narrative.

“Analysis paralysis” is born from ignoring the fact that reality is in charge. Mental health isn’t about being right; it’s about loving reality unconditionally — especially when it’s uncomfortable.

Without a frame, an idea isn’t useful; it’s just noise. An automated flood of perspectives paralyzes the intimate process of making meaning. Abstractions that can mean anything end up meaning nothing. We get stuck in an infinite loop of interpretation.

In software, this is known as accidental complexity: the self-serving bloat that smothers the essential complexity required for a system to function. While essential complexity drives useful behavior, accidental complexity just consumes resources to justify its own existence.

These abstractions are mental parasites. They feed on themselves without delivering a single gram of value to real life.

Only when you accept constraints — the rules of the real game vs. the rules of the pretend game — does an idea become practical. Claiming that “everything is relative” is a cheap trick: an absolute premise masquerading as humility to evade scrutiny to install a mistake.

Vagueness is an intellectual smoke screen. Ambiguity is the refuge of those afraid to be wrong. If you aren’t willing to despise the false and accept that some things are simply true, you will never do anything that matters.

Reality is not an opinion. It’s the ground beneath your feet.

Stop debating the map and start walking on solid premises that defend themselves through self-evidence — or accept that you prefer the brief illusion of safety of a paralysis that history will simply evaporate.

I was about to make a mistake that would have cost me months of refactoring — and a friend’s question saved me. It was early in the 2000’s but I vividly remember a project I worked on where everything changed for me. I was deep into implementing the system, and I had a design doubt that, although I expressed it in a rudimentary way like “how do I do this?”, I knew it would condition the future of that software. I’d just devoured The Design Patterns Smalltalk Companion and Smalltalk Best Practice Patterns by Kent Beck, and I was eager for the ideas in those books, ready to fit patterns like Singleton, Command, or Strategy into every corner of the design.

At the time, we used to consult colleagues and friends for design feedback. While I enthusiastically explained to one how one pattern would solve this problem and another would fit perfectly into that other part, this friend interrupted me with a phrase that stuck in my mind: “But why, instead of trying to fit patterns into your design, don’t you focus on properly modeling what your models should do? From that, you might see known patterns emerge, but it’s from modeling correctly that they arise.”

Everything seemed to happen in slow motion at that moment.

It wasn’t about forcing preconceived technical structures from the outside in, but about capturing the essence of the real world that the software aimed to represent and modeling it modestly from its parts toward the totality of the desired behavior.

This meant refraining from overly premature bottom-up solution building and instead promoting a modest, top-down-inspired bottom-up approach.

My confused ego felt the cold bucket of water, but my inner Aristotle enthusiastically approved the insight of guiding the design down that path.

This insight not only transformed my approach to programming but also showed me how software design can be more resilient over time, flexible, and maintainable.

And it’s obvious why.

Implementation details can change like a library update, but the essence, the reasons for something’s existence, is much harder to change. If the structure successfully captures that, it will be much more long-lived and resistant to the passage of time.

This principle becomes even more relevant now that AIs have inverted the cost of execution.

When code generation is cheap, design quality becomes your competitive advantage.

We’ve always been accustomed and adapted to the idea that executing a project is the expensive part. “Everything” in the industry is optimizing for that. But with synthetic assistants, producing functional code and execution is no longer the most costly part.

Reality vs. Necessary/Unnecessary Abstractions

At its core, software is nothing more than a simulation of the real world. A digital mirror that reflects processes, entities, and relationships in the domain we’re trying to solve. When we prioritize modeling this reality—the actors, their responsibilities, and inherent behaviors—we create systems that flow naturally, like a river following its course.

Every system is necessarily an abstraction of reality that we call “works well” when it models it with high fidelity for what we wanted to manage. But if it has no bugs and its utilitarian purpose doesn’t distract us, we quickly forget that it’s a reflection of reality. That it’s still a structural and dynamic model of real-world processes and objects with their natural tendencies.

Invention vs. Discovery

Kent Beck captured it perfectly in his works: “Patterns are not invented; they are discovered.” They aren’t recipes we apply from a book to impress, but “accidental consequences of design” that appear organically when proper and complete modeling has been done. Forcing a pattern, like imposing a Singleton where it wasn’t entirely necessary, creates a restriction that will have consequences.

Speaking of Singleton, this one in particular doesn’t let you scale horizontally whatever you’re modeling. Almost everything you initially thought to solve with a Singleton was actually a way to move the project forward by referencing that object from different places of the codebase, because at the start of the project, it’s not so clear how those “different places” can be properly coupled. You solve it with a Singleton, but later you figured out it was better to instantiate it normally at startup and pass it downstream to the modules that need it.

The sequence in which your mind found the best abstractions chain was not linear and this is natural for us. But we need to be mindful now because AIs have a different nature and might not have that restriction (they have other limitations of their own).

And this philosophy transcends languages: in Smalltalk, where everything is an object, it’s easy to fall into the temptation of patterns by default. But in other non-pure languages too. You can perfectly do all the wrong Separations Of Concerns in your Rust modules.

Even in generative AI environments, the principle is not only the same but its value is renewed and amplified.

Ask your design: “Does this reflect the real domain, or is it a forced abstraction?” By doing so, you’ll see how patterns emerge on their own, making your design more future-proof—capable of evolving without breaking—and flexible to adapt to new requirements without massive refactorings.

Contrast this with a hacked design: forced patterns create high coupling and scattered logic, confusing even advanced AIs. It’s going to leave your project slower and more complicated to maintain. In a thought experiment, imagine asking an AI to add a feature to an e-commerce system. If the domain is well-modeled—products that “know” how to promote themselves, carts that calculate totals on their own—the AI generates precise and maintainable code. If not, it ends up patching hacks, perpetuating technical debt despite fitting some scattered unit tests that pass and tell you everything’s fine. Maybe in that commit, but in the next feature you want to add, you’ll feel bogged down.

Barriers

The pressure of deadlines pushes us toward quick solutions: “I couple this here from another module that has nothing to do with it and solve it today.” Not all tech debt is bad, but keeping it under control requires being attentive to its consequences.

Another barrier is technical inertia: in large teams, it’s tempting to copy existing structures, even if they don’t model the current domain. I do it this way because they solved it that way over there, “it’s safe.” And with AIs, some think “the AI will fix it,” but poor modeling only amplifies problems in automatic generations.

A particularly subtle barrier is how our ability to solve technical problems—those ingenious hacks that save the day with “clever” implementations—can negatively condition high-level design. It’s easy to fall into the trap of thinking in bottom-up solutions, where low-level code dictates the architecture, instead of top-down, where the domain guides the design. This leads to rigid systems, where the technical “how” eclipses the “what” of the real domain. The details, convenient at first, later distance you from reality.

Techniques to avoid falling into this problem

Explicit Separation of Phases: Divide the process into clear stages. First, dedicate exclusive time to modeling the domain without touching code: use whiteboards, diagrams, or even conversations with stakeholders to capture real entities and flows. From those flows, you can get an idea of which methods are essential, thus a notion of what would result in a minimal, elegant, and maintainable API. Only then, implement. This defends you from low-level details invading the high level. For AIs, ask them to generate domain models based on natural descriptions before code, and have them unblock you or give you more than one approach to the solution that solves a problem.

Competing Design Ideation: Before committing to an implementation, create an ideation phase where multiple design approaches compete for approval. This used to be costly and laborious — which explains the natural resistance to doing it — but it’s become brutally cheap now. Generate at least three different ways to model the solution to the same problem, ranging from minimalistic to comprehensive, each with its own trade-offs and domain alignment. Make these design ideas explicitly compete by evaluating them against domain fidelity, maintainability, and future flexibility. They will be fantastic conversation starters between engineers. It prevents premature commitment to a single approach that might be a forced pattern in disguise. The winning design should emerge from how well it captures reality and prepares you for the future, not from technical convenience. With AIs, ask them to generate multiple architectural approaches for the same problem, then contrast them. Have them argue for and against each approach from a domain modeling perspective. This competitive ideation surfaces hidden assumptions and forces you to justify design choices based on reality before patterns.

Test-Driven Development with Focus on Behaviors (BDD): Write tests that describe domain behaviors in natural language (using tools like Cucumber or SpecFlow). This forces you to think about “what the system does” from the user or domain perspective, not “how I implement it.” Your low-level skills are used to pass the tests, but they don’t dictate the design. AIs can generate these initial tests, reinforcing the high-level focus. Try having an AI make you a PRD and ask it to generate user stories and those tests. They usually do a great job with that part.

Analogies and Real-World Metaphors: Before designing, relate the problem to a non-technical scenario. For example, compare an order system to a real restaurant: Who handles what? This elevates thinking above code-specific hacks. It makes you think about the “universality” of a certain process, and your mind will be more eager to capture its essence. Ask AIs for metaphors, have them give you several to expand perspectives. It doesn’t matter if not all fit; the technique is that by reading them, you’ll find the one that fits best faster because you have better context than the AIs.

Retrospectives and Design Journaling: At the end of each iteration, ask yourself: “Does my design reflect the domain or my technical preferences?” Keep a journal of decisions to detect conditioning patterns. In my repos, I even use a DECISIONS.md for this. In teams with AIs, use prompts so they analyze your code and point out if the low level dominates.

Exercises in Refactoring Toward Domain: Take existing code with hacks and refactor it focusing only on moving behaviors to domain-correct actors, ignoring premature optimizations. Do it as a regular practice. Ask an AI to propose refactorings, comparing versions to internalize the insight. Try telling it that you have a preference for “One-way dependency discipline.” It will definitely propose things that improve Separation of Concerns and how modules depend on each other.

Interdisciplinary Collaboration: Involve non-programmers (like domain experts) in modeling sessions. Their inputs keep the focus on reality, diluting technical bias. If it’s hard to schedule, customized AIs can simulate these experts via role-playing in prompts.

These techniques aren’t just tricks; they’re tools to cultivate a mindset where the domain rules and technical details serve, not the other way around. By applying them, you not only avoid common traps but also prepare your systems for a future where humans and AIs co-create without friction, with designs that evolve gracefully instead of breaking under the weight of accumulated hacks. It’s like going from being a reactive coder to a visionary architect, where every decision honors the reality of the problem.

The understandability of your basecode becomes a feature.

A good design is never an accident.

It’s always deeply intentional.

And often, the best one is discovered after removing everything that’s not essential.

Does your inner Aristotle approve?

Before writing a single line of code, start your next feature by asking:

• ‘What is the real-world process I’m modeling?’
• ‘What are the restrictions I’ll be imposing with this necessarily incomplete model of the real-world I’m coding?’

In the vast landscape of business, one truth remains immutable: you can’t negotiate genuine desire. It’s a lesson that traditional industries have tried to bend to their will, and even in the dynamic world of startups and tech products, it’s a concept that refuses to yield.

Consider, for a moment, the conventional approach to business. Picture a car dealership with a pushy salesperson who insists that their shiny sedan is exactly what you need. You may relent and make the purchase, but your heart doesn’t truly desire that vehicle. Sure, it serves a purpose, but it doesn’t inspire genuine passion

Now, imagine walking into an upscale fashion boutique. The well-designed storefront and carefully curated displays invite you to explore. No one pressures you to buy, but you find yourself irresistibly drawn to a stunning dress. It’s not because someone coerced you; it’s because the product spoke to your imagination using it, your sense of style and your possible expressions when using it. That’s genuine desire in action.

For startups and tech products, the same principle applies. Let’s say you’ve developed an innovative mobile app, but your initial marketing strategy revolves around intrusive pop-up ads and persistent notifications. You may see a temporary surge in downloads, but are these users genuinely desiring your app? More often than not, they’re merely capitulating to persistent marketing tactics. What do you think the churn would be?

On the other hand, consider the story of a small tech startup that created a x10 solution as an app. Instead of bombarding potential users with ads, they offered a series of well-crafted blog posts and videos explaining how their app could transform daily life. It will help its users to get specific jobs done. They nurtured a community of early adopters, actively engaging with feedback and suggestions. Soon, users weren’t just downloading the app; they were enthusiastically sharing it with friends. Why? Because the app genuinely resonated with their needs and desires.

Something that is key for a successful product is creating content that provokes attractiveness. It works on seduction rather than pushing an outcome. You cannot negotiate desire because desire happens inside your audience, not you.

Are you listening to your audience? Can you express their needs in better terms than they do?

Can you craft the narratives that resonate emotionally with them?

What do you stand for? Is that desirable for them?

You don’t have control over the audience needs and desires.

Good news is that you do have control over designing environments where remarkable solutions can be experienced and curiosity can be awaken.

And that’s how it starts.

In the realm of software development, crafting code that remains maintainable, flexible, and scalable stands as an utmost priority. And when delving into the concept of scalability, I’m considering not only the system’s load capacity but also your ability to maintain it, essentially wielding it as a tool to conquer complexity. To achieve this, developers often embrace design principles that steer them in writing this type of high-quality code. One such set of principles is known as SOLID, an acronym representing five essential tenets in object-oriented programming.

Let’s delve into what each of these principles entails:

1. Single Responsibility Principle (SRP)

The Single Responsibility Principle emphasizes that a class should have only one reason to change. Intentionally resisting designs that would mix responsibilities. In other words, a class should always have only one responsibility. This principle encourages us to break down complex classes into smaller, focused ones, each responsible for a single task. By adhering to SRP, code becomes more modular and easier to maintain, as changes in one area of functionality are less likely to affect unrelated parts. Discipline on this will enable your team to architect a maintainable and flexible dependency tree.

2. Open/Closed Principle (OCP)

The Open/Closed Principle dictates that software entities (classes, modules, functions) should be open for extension but closed for modification. This means that you should be able to add new features or behaviors without altering existing code. Think about software as a Lego masterpiece. When you want to add a shiny new block, the last thing you want is to disassemble the entire structure. OCP is the guardian of extensibility. Discipline on this requires that your code in a way that welcomes new features without sending shockwaves through the old ones.

3. Liskov Substitution Principle (LSP)

The Liskov Substitution Principle emphasizes that objects of a subclass should be able to replace objects of the parent class without affecting the correctness of the program. In other terms, subinstances should be usable interchangeably with parent instances without causing errors or unexpected behavior. Adhering to LSP ensures that the relationships between classes are well-defined and intuitive. If you’re familiar with Smalltalk, you can think if it wouldn’t be the case for senders of self subclassResponsibility.

4. Interface Segregation Principle (ISP)

Ever been to a buffet where you’re forced to eat everything? Not fun, right? In code, the same applies. The Interface Segregation Principle suggests that clients should not be forced to depend on interfaces they do not use. In essence, this means that you should create specific interfaces for specific client needs, rather than creating large, monolithic interfaces. By doing so, you prevent clients from being burdened with unnecessary methods, promoting cleaner code and more focused APIs.

5. Dependency Inversion Principle (DIP)

This one’s like inviting your in-laws to manage your household for a change. Proposed by Robert C. Martin, this principle aims to create a more flexible, maintainable, and easily testable codebase by reversing the traditional flow of dependencies. In simpler terms, DIP suggests that business logic modules, should not directly depend on modules that handle implementation details and specifics. Instead, both should depend on abstractions that help them to coordinate the system functionality. This principle maintain the codebase more flexible and facilitates easier testing and maintenance.

In conclusion, the SOLID principles provide a set of guidelines that help software developers create maintainable, adaptable, and robust code. By adhering to these principles, you can write code that is easier to understand, modify, and extend, ultimately leading to more efficient development and reduced chances of introducing bugs. Whether you’re a seasoned developer or just starting your programming journey, understanding and applying the SOLID principles can significantly elevate the quality of your code.

In my previous article How to Create a Pharo Smalltalk Plugin, I outlined how to create a Pharo Smalltalk plugin. However, since then, I’ve discovered a more convenient way to produce these plugins using the PharoPluginBuilder and StarterPlugin. In this post, I wanted to inform and describe the idea of this simplified process of creating a Pharo Smalltalk plugin.

I’ve run it several times in macOS and these steps work fine. I’ll appreciate feedback on how it goes for other platforms which should work but I didn’t find the time to try.

Using the new simplified procedure of PharoPluginBuilder, includes:

1. The clone of the PharoPluginBuilder repo.
2. Having an ide/ dir where you have a Pharo image meant for being the IDE to develop your plugin.
3. Having a dependencies/ dir where this setup will sit A) a pharo-vm project clone that is required and B) any third party library that you would use.
4. The dist/build directory where you will find the binary built artifact of your plugin.

Follow that README.md and get your own:

Further simplification

Guillermo Polito has been experimenting with further simplifications and build conveniences in this branch https://github.com/guillep/pharo-vm/tree/feat/pluginbuilder which would allow to use it like this:

# Configure cmake
cmake -B build -S repo/path

# Generate the vmmaker image with the plugin code
cmake --build build --target StarterPlugin_IMAGE

# Generate only the sources
cmake --build build --target StarterPlugin_generate_source

# Build the plugin
cmake --build buildv2 --target StarterPlugin

In conclusion, creating a Pharo Smalltalk plugin doesn’t have to be a complex process. While there is space for improving this further, by using the PharoPluginBuilder and StarterPlugin, you can quickly and easily create a plugin that extends the functionality of the Smalltalk language. Follow the steps outlined in this post, and you’ll be on your way to creating your own custom plugin in no time.

As businesses increasingly rely on software to deliver their products and services, ensuring that their production applications are running smoothly and efficiently becomes a must for maintaining what makes your app to be dependable on: application reliability, performance, and availability.

One critical aspect of monitoring production apps is measuring resource usage, including CPU, memory, and network utilization and that’s very well covered by many solutions. As previously mentioned, I particularly like The TLIG Stack for that. These metrics can provide valuable insights into the application’s health, allowing teams to identify performance bottlenecks and detect potential issues before they escalate into larger problems.

But what about when we want to not be blind about how resources are used by every instance of an app running on Pharo Smalltalk virtual machines?

When it comes to monitoring this, from the operations point of view, your Pharo images need to not be black boxes anymore. You need to have inner visibility on how the computing resources are used by your app in each of these VMs.

Enter Pharometer, a Zinc delegate for sampling Pharo metrics in a InfluxDB friendly format.

Pharo Smalltalk is a powerful and dynamic programming language that offers significant flexibility hence performance to grow features, but this can make it challenging to operate as you deploy versions because its resource usage could vary without you having a quick feedback loop about it. This creates a feedback gap. By monitoring the internal resource usage of every Pharo Smalltalk Virtual Machine, teams would close this feedback gap and more easily identify and resolve service performance issues, ensuring that their production applications remain fast, reliable, and available to users as any dependable service would.

When searching for what was already existing, I came across this nice blog post from Pierce Ng Telemon: Pharo metrics for Telegraf showing the idea of using TIG for collecting and displaying Pharo Smalltalk apps’ metrics.

Pierce’s article got me encouraged to do my own TIG setup, thank you Pierce! Although it was great at the beginning, I started to feel I needed to add a couple of missing parts for using it to operate production services: logs aggregation and querying and availability monitoring and alerts. After researching options, I’ve settled with Loki (fed by Promtail) and Kuma.

By the way, here you can see more on how to use docker-compose to have all that running in a server The TLIG Stack.

Open the hood

Once the basic monitoring with the TLIG stack is available, we can go to the next level and add a nice Grafana dashboard displaying what we can collect using Pharometer to see the performance details of running Pharo images.

You need two things for that to happen:

1. Pharo images with your app responding values. This is solved using a customized Pharometer in your running image.
2. Telegraf configured to periodically sample these values. This is satisfied by configuring a custom HTTP plugin in Telegraf.

Pharometer is a single class program designed to work as a Zinc delegate. It has a name, tags for labelling, fields (that you can think as label and measured value pairs), and a context that can be used to optimize “costly” calculations to aid during the rendering process. Is this context dictionary, the place where you can store a value that you can re-use in calculating the metric of more than one field without having to compute the costly value more than once.

Let’s see an example to understand its convenience.

Here, monitor Socket instances, we’re adding one context builder to count all the instances of the Socket class, which we can consider as a costly operation we want to do once:

| pharometer |
pharometer := Pharometer named: 'pharo'.
pharometer addContextBuilder: [ :ctx | ctx at: #sockets put: Socket allInstances ].
pharometer addTag: #app value: 'app-42'.
pharometer addTag: #image value: [ Smalltalk image imageDirectory pathString ].

pharometer
  addField: #totalSockets
  value: [ :ctx |
    "Quantity of all Socket instances"
    (ctx at: #sockets) size  ].

pharometer
  addField: #connectedSockets
    value: [ :ctx |
    "From all Socket instances, quantity of those which are connected"
    ((ctx at: #sockets) select: [ :e | e isConnected ]) size ].

pharometer
  addField: #validSockets
  value: [ :ctx |
    "From all Socket instances, quantity of those which are in a valid state"
    ((ctx at: #sockets) select: [ :e | e isValid ]) size ].

The render method will create a new context by sequentially evaluating all the contextBuilder closures that you added (if any).

The previous example would grab all the current instances of Socket once and render these 3 measurements derived from it:

pharometer render.
"'pharo,app=app-42,image=/Users/seb/Developer/blah-project totalSockets=14,connectedSockets=4,validSockets=12'"

Pharometer is clean and doesn’t have any default values or tags. And yet, is flexible enough to be customized to serve whatever fresh measurements you make it calculate. All by efficiently consuming them during the rendering phase when the field closures get executed.

Although it’s clean, I’ve added some convenient presets methods that will add different categories of measurements. At least I wanted a way to keep an eye on sockets, memory, threads and "other" resources.

Note that, while addMemoryMetrics doesn’t make any use of the context builder:

addMemoryMetrics

  self
      addField: #freeSize value: [ Smalltalk vm freeSize ];
      addField: #edenSpaceSize value: [ Smalltalk vm edenSpaceSize ];addField: #youngSpaceSize value: [ Smalltalk vm youngSpaceSize ];addField: #freeOldSpaceSize value: [ Smalltalk vm freeOldSpaceSize ];
      addField: #memorySize value: [ Smalltalk vm memorySize ];
      yourself.

addThreadMetrics makes a convenient use of it:

addThreadMetrics
    self
        addContextBuilder: [ :ctx |
          ctx at: #processes put: Process allInstances ];
        addField: #totalProcesses
        value: [ :ctx | (ctx at: #processes) size ];
        addField: #suspendedProcesses
        value: [ :ctx |
          ((ctx at: #processes) select: [ :e | e isSuspended ]) size ];
        addField: #terminatedProcesses
        value: [ :ctx |
          ((ctx at: #processes) select: [ :e | e isTerminated ]) size ];
        addField: #terminatingProcesses
        value: [ :ctx |
          ((ctx at: #processes) select: [ :e | e isTerminating ]) size ];
        yourself

Putting it all together

If you don’t have yet custom metrics you want to sample, here is a handy setup that will measure basic VM resources usage for you:

| pharometer zincServer |
pharometer := (Pharometer named: 'pharo42')
  addMemoryMetrics;
  addSocketMetrics;
  addThreadMetrics;
  addOtherMetrics;
  yourself.
  zincServer := ZnServer on: 8890.
  zincServer delegate: pharometer.
  zincServer start.

With this as part of you app build and startup process, all that is left is to consume it. When using the TLIG stack, this is done with a generic Telegraf HTTP plugin.

If you use the TLIG stack from this repository, you’ll find a conf/telegraf/telegraf.conf file that is a massive yml file.

To add the plugin that would sample your Pharometer measurments, search for Read formatted Pharo metrics from an HTTP endpoint and all you need to do there is to tell, in which URL, Pharometer is rendering that output

In this example, it’s using http://host.docker.internal:8890\" because that TLIG stack runs using docker-compose and host.docker.internal is a way to make it find when your Pharo app is reachable from the host. Have in mind this good for a starter setup but this will vary depending on how you deploy and how complex your deployed targets are.

Here is a sample of a Telegraf working HTTP plugin:

# Read formatted Pharo metrics from an HTTP endpoint
[[inputs.http]]
## One or more URLs from which to read formatted metrics
urls = [
  "http://host.docker.internal:8890"
]
## HTTP method
method = "GET"

A pending follow up to this setup is find a way to conveniently setup Telegraf to monitor a bunch of Pharo Smalltalk running images and make a overview dashboard for a cluster and a per-Pharo dashboard when you want to drill down and check its performance details.

I hope that by now you have a better sense of how to monitor services that are built on top of Pharo Smalltalk applications in production and that Pharometer, as a Zinc delegate, can provide valuable insights into the application’s health by measuring resource usage.

Looking forward to see people sharing Grafana dashboards customized and useful to other people running Pharo based services.

Have a happy Grafana dashboarding process based on TLIG and Pharometer!

I’m excited to announce that the Pharo Consortium has been approved as an organizer for Google Summer of Code 2023! As a mentor for the Pharo TensorFlow plugin project, I’m thrilled to be a part of this program and to help developers to work on a project for the Pharo community.

Google Summer of Code is an annual program that brings together student developers from around the world to work on open source projects with experienced mentors. As in previous years, this is a great opportunity for students to gain practical experience in software development using Pharo Smalltalk and doing so by contributing to real-world projects that have an impact on the whole open source community.

The project I’m going to help with is the one we proposed last february here, Bringing TensorFlow to Pharo.

The Pharo TensorFlow plugin project aims to integrate TensorFlow, a popular machine learning library, with the Pharo programming language. This will enable Pharo developers to efficiently incorporate high-performing computations that are typical in a hot segment of the industry right now: machine learning and everything AI. And with a Pharo TensorFlow Plugin, the capabilities of the Pharo applications are not going to be limited to the CPU anymore. They will start to be able to yield GPU power to execute all the powerful features and algebraic conveniences that TensorFlow provides.

Together with Sebastian Jordan, we’ll be mentoring this project to work closely with student developers and guide them through the development process, answer their questions, and help them overcome the challenges that they encounter along the way. I’m excited to see what they will achieve and to help them make a meaningful contribution to the Pharo community.

If you’re a student developer who is interested in participating in Google Summer of Code 2023, we encourage you to check out the program website and explore the various projects that are available. And if you’re interested in the Pharo TensorFlow plugin project, we’d love to hear from you! Feel free to reach out to us to learn more and to get involved.

We look forward to a productive and exciting Google Summer of Code 2023, and we can’t wait to see what the future holds for the Pharo community and the open source projects that we’re working on. Stay tuned for more updates and progress reports throughout the summer!

Monitoring is an essential part of any modern infrastructure. It helps you keep an eye on system performance, detect anomalies, and identify potential issues before they become critical. With the right tools, monitoring can be a straightforward process that provides valuable insights into your system’s health.

However, if you’re like me, you can feel that setting up an effective monitoring system today can be daunting, especially for those who are new to the field. There are a plethora of tools and technologies available, and it can be difficult to know where to start.

In this article, I will show you how to set up Promtail, Telegraf, InfluxDB, Loki, and Grafana to monitor your system’s performance and logs plus Kuma for service availability and alerts. I’ve selected this toolchain because is reasonably straightforward to setup, shows good potential and flexibility for further growing needs.

And I’ve created this docker-compose setup TLIG v1.0.2 so you can have a reference to use as a starter.

By the end of this article, you will have a good understanding of how to set up a monitoring system for your infrastructure, and an idea on how you’ll be able to customize it to meet some of your specific needs.

What to Monitor

With a system’s design approach, we can identify the critical components of your infrastructure and then set up monitoring for those components so you have the right monitoring at the right levels. Any component in your service tech stack that is sensible to computing resources should be monitored for performance.

Sometimes a component could go down and the service would still be able to operate in a degraded state. Sometimes it won’t be able to and you need to receive an adequate alarm pointing to that.

Let’s review their categories:

Infrastructure. Components can include servers, network devices, and storage systems. It’s essential to monitor the health and performance of these components to detect issues that may lead to downtime or data loss. Kuma is going to help with this.

Application Services. These are the backbone of any system. Monitoring the performance of the backend service is essential to ensure that requests are being processed efficiently and without errors. Telegraf will help here by efficiently collecting periodic measures as instructed in its customizable configuration and plugins. The availability status is going to be covered by Kuma and its performance will be displayed in Grafana dashboards.

Application Logs. Logs are the most obvious and expected way for headless services to leave a human readable trace of their activity for any system. They provide valuable information about what’s happening in your application and have big value to be used to diagnose issues, identify trends, and even track user behavior. Loki will be used to have this accessible in one place and easy to query.

Metrics. Metrics provide a high-level view of system performance over time. They help to identify trends and potential issues before they become critical. Metrics can include CPU usage, memory usage, disk space, network traffic and the usage of many other resources. Again, all of the performance details are going to be displayed in Grafana dashboards.

Let’s take a moment to review each component and its function:

Promtail

Promtail is a log collector and parser that sends logs to Loki. It can tail log files, filter logs based on patterns, and enrich log data with metadata. Promtail is designed to be highly scalable and can handle a large number of log streams.

Telegraf

Telegraf is a plugin-driven server agent that can collect and send metrics to a variety of datastores. It supports a wide range of input plugins, including system metrics, network metrics, and Docker stats. Telegraf can also transform and aggregate metrics before sending them to the datastore.

InfluxDB

InfluxDB is a time-series database that stores and queries time-stamped data. It provides a SQL-like query language for querying and aggregating data. InfluxDB is highly scalable and can handle millions of writes per second.

Loki

Loki is a horizontally scalable, highly available log aggregation system. It is designed to be a cost-effective way to handle large amounts of log data. Loki can ingest logs from various sources, including Promtail, and allows you to search and filter logs based on labels.

Grafana

Grafana is a popular open-source platform for data visualization and monitoring. It can connect to various data sources, including InfluxDB and Loki, and provides an appealing web-based interface for creating and sharing dashboards. Grafana supports a wide range of visualization options, including charts, tables, and alerts.

Now that we have a good understanding of each component’s role in the monitoring stack, let’s move on to setting up the monitoring system using Docker Compose as found in TLIG v1.0.2.

docker-compose.yml

version: "3"

networks:
  tlig:

services:
  loki:
    image: grafana/loki:2.4.0
    init: true
    env_file:
      - .env
    volumes:
      - ./conf/loki:/etc/loki:rw
    ports:
      - ${DOCKER_LOKI_PORT}:3100      
    restart: unless-stopped
    command: -config.file=/etc/loki/loki-config.yml
    depends_on:
      - promtail
    networks:
      - tlig
  promtail:
    image: grafana/promtail:2.4.0
    init: true
    env_file:
      - .env
    volumes:
      - /var/log:/var/log:ro
      - ./conf/promtail:/etc/promtail:rw
    restart: unless-stopped
    command: -config.file=/etc/promtail/promtail-config.yml
    networks:
      - tlig
  influxdb:
    image: influxdb:2.1.1
    init: true
    volumes:
      - ./data/influxdb:/var/lib/influxdb2:rw
    env_file:
      - .env
    entrypoint: ["./entrypoint.sh"]
    restart: on-failure:10
    ports:
      - ${DOCKER_INFLUXDB_INIT_PORT}:8086
    networks:
      - tlig
  telegraf:
    image: telegraf:1.19
    init: true
    volumes:
      - ${TELEGRAF_CFG_PATH}:/etc/telegraf/telegraf.conf:ro
    env_file:
      - .env
    depends_on:
      - influxdb
    restart: unless-stopped
    networks:
      - tlig
  grafana:
    image: grafana/grafana-oss:8.4.3
    init: true
    user: ${USER_ID}
    volumes:
      - ./data/grafana:/var/lib/grafana:rw
    env_file:
      - .env
    depends_on:
      - telegraf
      - loki
    restart: unless-stopped
    ports:
      - ${GRAFANA_PORT}:3000
    networks:
      - tlig
  kuma:
    image: louislam/uptime-kuma:1
    init: true
    container_name: kuma
    env_file:
      - .env
    volumes:
      - ./data/kuma:/app/data:rw
    ports:
      - ${KUMA_PORT}:3001
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

Create a .env for yourself based in this .env.sample:

DOCKER_INFLUXDB_INIT_MODE=setup

## Environment variables used during the setup and operation of the stack
#

# Primary InfluxDB admin/superuser credentials
#
DOCKER_INFLUXDB_INIT_USERNAME=admin

# Make sure this pwd is not too short so Influx doesn't reject it.
DOCKER_INFLUXDB_INIT_PASSWORD=adminpwd1234

# Generate your own with `openssl rand -hex 32`
DOCKER_INFLUXDB_INIT_ADMIN_TOKEN=blahblahblahrandomstringtoken

# Primary InfluxDB organization & bucket definitions
# 
DOCKER_INFLUXDB_INIT_ORG=yourorganization
DOCKER_INFLUXDB_INIT_BUCKET=telegraf 

# Primary InfluxDB bucket retention period
#
# NOTE: Valid units are nanoseconds (ns), microseconds(us), milliseconds (ms)
# seconds (s), minutes (m), hours (h), days (d), and weeks (w).
DOCKER_INFLUXDB_INIT_RETENTION=4d

# InfluxDB port & hostname definitions
#
DOCKER_INFLUXDB_INIT_PORT=8086 
DOCKER_INFLUXDB_INIT_HOST=influxdb 

# Telegraf configuration file
# 
# Will be mounted to container and used as telegraf configuration
TELEGRAF_CFG_PATH=./conf/telegraf/telegraf.conf

# Loki port definition
# 
# 
DOCKER_LOKI_PORT=3100
DOCKER_LOKI_GRPC_PORT=9096

# Promtail port definition
# 
# 
DOCKER_PROMTAIL_PORT=9080
DOCKER_PROMTAIL_GRPC_PORT=0

# Grafana port definition
# Grafana default uses 3000 but let's move that elsewere, since that's
# a popular port for many developing setups.
GRAFANA_PORT=3008
USER_ID=xxxx #replace xxxx with what you have for `$(id -u)`

# Kuma port definition
KUMA_PORT=3009

For running it in one host, you should be good by setting the username, password, token, organization name and bucket name for InfluxDB and all the ports and USER_ID.

You’ll be able to further config Promtail, Loki and Telegraf editing the files in ./conf/. For example, you’ll see that promtail-config.yml has a commented docker job for collecting all container logs in Loki which is quite neat.

With that ready, you can start it with:

docker-compose up -d --force-recreate

Grafana first time login

Open Grafana GUI by navigating to http://localhost:3008 and, since it’s the first time, you can login using admin / admin and later change to proper credentials.

Go to Add your first data source and add Loki from the list. Use these http://loki:3100 for the URL field (or the port number value you had in your .env for it). Press the Save & test button.

Back to Grafana’s home, add another data source and this time add InfluxDB from the list.

Use these values:

Query language: Flux.

URL: http://influxdb:8086.

Basic auth: off.

Organization: use what you have set for DOCKER_INFLUXDB_INIT_ORG in your .env file. Press the Save & test button.

Kuma

If you navigate to http://localhost:3009 you’ll have Kuma ready to add new monitors that will be very easy to setup to your health-check endpoints.

NGINX

For deploying all this in your servers, all the services can be proxied in a simple way as you would expect, except Grafana and Kuma that will need a bit of attention for its WebSockets needs. Here is how you Configure NGINX for Grafana and here how to have Kuma as Reverse Proxy.

In conclusion, setting up an effective monitoring system for your infrastructure is an essential task that can help you identify potential issues before they become critical, detect anomalies, and keep an eye on system performance. While there are many tools and technologies available, Promtail, Telegraf, InfluxDB, Loki, Grafana, and Kuma are an excellent combination to get started with. And with the TLIG v1.0.2 docker-compose file, hopefully you have some help to start doing it.

Remember that monitoring is an ongoing process that requires continuous improvement and adjustment. As your infrastructure grows, your monitoring system should also evolve to meet new challenges and requirements. With the right tools and strategies, you can ensure the health and reliability of your systems, and proactively address any issues that may arise.

I can easily see how this article might need a follow up to monitor a service managed with Kubernetes and running microservices developed with Pharo Smalltalk, of course 😊

Pharo is a powerful open-source Smalltalk-based programming language and environment that has been widely used for research and development in various fields. Specially Pharo at Inria, France’s National Institute for Research in Digital Science and Technology. However, the lack of a native plugin for TensorFlow, a popular open-source machine learning framework, has been a major limitation for high efficiency AI development with Pharo. I’ve written this post to let you know that, I’ve proposed a Google Summer of Code 2023 project to create a TensorFlow plugin for Pharo, which will unlock the full potential of Pharo for production grade AI development.

The goal is to create a TensorFlow plugin for Pharo that can be used directly by Pharo’s C VM, allowing Pharo to take full advantage of the silicon of your graphical processing unit so you have an efficient and powerful way to do mining of that GPU power for any algebra intensive peoject, Machine Learning and AI projects in particular. With this plugin, Pharo will be able to perform AI tasks such as deep learning, neural network training, and image recognition using TensorFlow with no need for additional bridges or third-party libraries that could add significant complexity to any project setup and development and debug process.

The completed project has the ambition to deliver a plugin that provides all the primitives to the TensorFlow API, with at least one unit test to ensure quality assurance. This will enable Pharo developers to use TensorFlow for world class AI development, making Pharo a top-tier platform for machine learning or any synthetic intelligence application.

The project requires basic C programming skills, familiarity with how the Pharo VM is created, basic familiarity with Slang, and strong communication skills. Prior experience in creating a Pharo plugin is preferred.

Extending the Squeak Virtual Machine by Andrew C. Greenberg is a great read for getting up to speed on the basics of extending Smalltalk VM functionality.

Together with Sebastian Jordan and Oleksandr Zaitsev from the Pharo community, we’ll mentoring the students taking on this project to help them make it real. As a first step in this direction, I’ve published How to Create a Pharo Smalltalk Plugin here to remove any friction of the developing process of Pharo plugins.

Hoping Google likes it and becomes real!

Want to be part of this?

Check the eligibility criteria in Google Summer of Code 2023: Call for Students and help us make this a new impactful resource for a new reality.

Creating a TensorFlow plugin for Pharo is an important step towards unlocking the full potential of this powerful language for AI development. I believe that this Google Summer of Code 2023 project will be an exciting opportunity for any student who is passionate about machine learning and interested in contributing to an open-source community. With the right skills and guidance, we can make TensorFlow a first-class citizen in the Pharo ecosystem, and enable Pharo developers to take on AI challenges with confidence.

Introduction

When working with Smalltalk, you sometimes wish to access functionality that exists only in a specific library or technology that you cannot or simply don’t want to reinvent. When you are in this scenario, two options come to mind:

1. FFI, or Foreign Function Interface, which is a mechanism to enable a program written in one programming language to interact with code written in another programming language. Essentially, a “bridge” that allows them to communicate and exchange information with each other.
2. Somehow make the Smalltalk Virtual Machine to have more primitives that extend its default functionality to produce this communication back and forth, from the Smalltalk code and these other libraries.

In developing terms, FFI is usually the fastest way to achieve this and, for Pharo, is extensibly covered in Unified FFI - Calling Foreign Functions from Pharo by Guillermo Polito, Stéphane Ducasse, Pablo Tesone and Ted Brunzie.

In this article, we’ll delve into the less-traveled road of extending the Pharo Virtual Machine with an external plugin by creating a HelloWorldPlugin. With this, I want to provide some clarity that could demystify the process of making extensions in this way by understanding the steps currently needed to achieve this in Pharo 9, as per February 2023.

Motivation

The primary motivation behind extending the Pharo Virtual Machine with a plugin is often performance, but in some cases, it can also simplify the process of accessing specific functionality. For instance, if you have a favorite library that can only be used by Python or Lua, as a Smalltalker, you may be forced to create a bridge to these technologies, adding additional setup instructions and increasing the complexity of your application’s technology stack. With the use of plugins, however, you can extend Smalltalk and keep the complexity of your tech stack to a minimum. After all, Smalltalk when used keeping an elegant software design, can be considered a tool for dominating complexity.

Back to performance, you will easily find cases where the FFI marshaling back and forth process might be considered too costly, and your Smalltalk application would find a more desirable alternative in getting dedicated primitives from a plugin to use the targeted functionality. You may be using plugins like FilePlugin, FloatArrayPlugin, SocketPlugin, and UnixOSProcessPlugin without even realizing it and, as you can imagine, they are all performance critical.

Let’s work on your new HelloWorldPlugin now. Here is the outline of the development cycle for it:

┌───────────┐                                
│MyPlugins/ │                                
└──┬┬───────┘               Plugin image     
   ││  ┌──────────────────┐       │          
   └┼─▶│HelloWorldPlugin/ │◀──────┘          
    │  └──────────────────┘                  
    │  ┌──────────┐                          
    └─▶│pharo-vm/ │◀──────────────┐          
       └──────────┘               │          
                       Code to produce builds

Setup procedure

You’ll need to do this once:

1. A directory where you’ll use a Pharo image for coding your plugin. Let’s refer to this as “the plugin image”.
2. A directory with a clone of the pharo-vm project
3. In the plugin image, you’ll install BaselineOfVMMaker which has all the infrastructure needed to produce the sources that you will later compile in a build process.
4. In the plugin image, you’ll checkout the Pharo9 branch from origin for compatibility with this guide.

Development procedure

You’ll iterate this part producing builds of your plugin until you get to the final version:

1. In the plugin image, you’ll locally create a new branch using that Pharo9 branch. That is your plugin development starting point. For this exercise we’ll create a this branch naming it HelloWorldPlugin.
2. In the plugin image, you’ll add the code of the HelloWorldPlugin class and its methods.
3. In the plugin image, you’ll update (needed only once) which the external plugins are going to get generated adding HelloWorldPlugin to the list and you’ll commit that. Note: you will only pick to commit that change and not any other automated change that Iceberg might detect.

Building procedure

1. From the MyPlugin directory, you’ll run the cmake command to configure the environment for compilation.
2. From the MyPlugin/build directory, you’ll run the make command to compile and produce the build.
3. From the MyPlugin/pharo-vm directory, you’ll edit plugins.cmake to make it include in the build the generated sources of HelloWorldPlugin.
4. From the MyPlugin directory, you’ll run the cmake command again to configure everything including the generated code of your plugin.
5. From the MyPlugin directory, you’ll run the make command to compile producing the binaries.

Note: If you don’t follow the sequence of the development cycle, you’ll notice that cmake can easily run into problems by not finding the sources of HelloWorldPlugin automatically generated in build/generated/64/plugins/src/HelloWorldPlugin. The first round of cmake and make (steps 8 and 9) are not actually to produce the binaries you’ll want, but only to have make producing the generated sources that you’ll use after plugins.cmake gets edited to include your plugin and then built with step’s 5 make.

Setup

Go to your favorite folder for your code and prepare a directory to work with this, here I’ll call it MyPlugins:

$ cd ~/yourFavoriteCodeDirForThis
$ mkdir MyPlugins
$ cd MyPlugins

Clone the Pharo code for building Pharo VMs:

$ git clone git@github.com:pharo-project/pharo-vm.git

Create the HelloWorldPlugin directory to have the image to produce the new code, so go ahead and grab a fresh pharo 9 and start it:

$ mkdir HelloWorldPlugin$ pwd
...blah/MyPlugins/HelloWorldPlugin
$  curl get.pharo.org/64/90 | bash
$  curl get.pharo.org/64/vm90 | bash
$ ./pharo

Off-topic, if you are like me, the first thing to do on fresh Pharo images is to tune the visuals by loading in a Playground:

Metacello new 
    baseline: 'PharoDawnTheme';
    repository: 'github://sebastianconcept/PharoDawnTheme';
    load.

Now, from this plugin image, add the repository from the cloned pharo-vm project using Iceberg and checkout the Pharo9 branch:

Now, load BaselineOfVMMaker:

Next, from the Pharo9 branch, create the new HelloWorldPlugin branch:

And now we can finally add your plugin code.

Go to SmartSyntaxInterpreterPlugin class. This one will be the superclass of your plugin.

Important: maintain HelloWorldPlugin in the VMMaker-Plugins package as required for automated code generation.

SmartSyntaxInterpreterPlugin subclass: #HelloWorldPlugin
	instanceVariableNames: ''
	classVariableNames: ''
	package: 'VMMaker-Plugins'

In the class side of HelloWorldPlugin add the moduleNameAndVersion method:

moduleNameAndVersion

	^ self moduleName ,Character space asString , Date today asString

In the instance side of HelloWorldPlugin add the primitiveGetHelloString and stringFromCString: methods:

primitiveGetHelloString

	<export: true>
	interpreterProxy
		pop: 1
		thenPush: (interpreterProxy stringFromCString:
			 'Hello from your HelloWorldPlugin.')

stringFromCString: aCString

	"Answer a new String copied from a null-terminated C string.
    Caution: This may invoke the garbage collector."

	<var: 'aCString' type: #'const char *'>
	| len newString |
	
	len := self strlen: aCString.
	newString := interpreterProxy
		             instantiateClass: interpreterProxy classString
		             indexableSize: len.
	newString ifNil: [ 
		^ interpreterProxy primitiveFailFor: PrimErrNoMemory ].
	self
		strncpy: (interpreterProxy arrayValueOf: newString)
		_: aCString
		_: len. "(char *)strncpy()"
	^ newString

If you’re wondering about that unusual looking code, that’s Slang, I’m not going to cover that here but is suffice for now to know that it’s a code generation tool originally used in Squeak and now used to produce the Cog virtual machine used in Pharo. Slang converts Smalltalk code into C source code, which is then compiled to produce a virtual machine or, as you’ll soon see, your HelloWorldPlugin. Slang basically helps to simplify the process of extending the Smalltalk virtual machine by providing an interface for generating multiplatform C code directly from Smalltalk code. This makes Smalltalk more maintainable and portable.

Done and said that, you’re almost ready to commit. The only missing piece of development is to tell VMMaker to use your class to create an external plugin.

Browse the PharoVMMaker>>generate:memoryManager: method and add the name HelloWorldPlugin to the array of external plugins.

The full method should be:

generate: interpreterClass memoryManager: memoryManager

	| platformDirectory |
	Author useAuthor: 'vmMaker' during: [ 
		VMMakerConfiguration initializeForPharo.
		(interpreterClass bindingOf: #COGMTVM) value: false.
		platformDirectory := self platformDirectoryFor: memoryManager.
		[ 
		(VMMaker
			 makerFor: interpreterClass
			 and: StackToRegisterMappingCogit
			 with: { 
					 #COGMTVM.
					 false.
					 #ObjectMemory.
					 memoryManager name.
					 #MULTIPLEBYTECODESETS.
					 true.
					 #bytecodeTableInitializer.
					 #initializeBytecodeTableForSqueakV3PlusClosuresSistaV1Hybrid }
			 to: platformDirectory
			 platformDir: platformDirectory
			 including: #(  )
			 configuration: VMMakerConfiguration)
			stopOnErrors: stopOnErrors;
			internal: #(  )
			external:
				#( FilePlugin SurfacePlugin FloatArrayPlugin HelloWorldPlugin );
			generateInterpreterFile;
			generateCogitFiles;
			generateExternalPlugins ] valueSupplyingAnswer: true ]

Now you can commit your changes completing the development procedure and ready to move on to the building procedure.

For the building procedure and to evade a chicken-egg kind of problem, we’re going to do a first round of running cmake and make commands that will autogenerate the C source code based on your methods written in slang and leave these source files ready to use at build/generated/64/plugins/src/HelloWorldPlugin (and likely also build/generated/32/...).

Go to your MyPlugins/ directory and run:

$ cmake -S pharo-vm -B build

After this run, you should see a list of plugins without HelloWorldPlugin, this is expected at this time. Also expected, is that you will not have yet the build/generated/ directory. We are going to produce it in the next command.

From MyPlugins/build run the make command to generate and compile everything for the first time:

$ make install

At the end of this process, you should see that build/generated/64/plugins/src/HelloWorldPlugin does exists now.

Time to tell cmake that it can configure a build including your generated sources. With your favorite editor open for editing the MyPlugins/pharo-vm/plugins.cmake file and add this above or below the configuration for Surface Plugin. We’re basically going to tell cmake that it should do with HelloWorldPlugin the same as with SurfacePlugin, build it from the sources as an external plugin.

Your edited plugins.cmake now should look like:

... 
#
# HelloWorld Plugin
#

add_vm_plugin(HelloWorldPlugin 
	${PHARO_CURRENT_GENERATED}/plugins/src/HelloWorldPlugin/HelloWorldPlugin.c)

#
# Surface Plugin
#

add_vm_plugin(SurfacePlugin 
	${PHARO_CURRENT_GENERATED}/plugins/src/SurfacePlugin/SurfacePlugin.c)

#
# FloatArray Plugin
#

add_vm_plugin(FloatArrayPlugin 
	${PHARO_CURRENT_GENERATED}/plugins/src/FloatArrayPlugin/FloatArrayPlugin.c)
...

Next, from MyPlugins directory, run cmake again:

$ cmake -S pharo-vm -B build

And at the end, you should find it lists your plugin:

... 
   B2DPlugin
   BitBltPlugin
   DSAPrims
   FileAttributesPlugin
   FilePlugin
   FloatArrayPlugin
   HelloWorldPlugin
   JPEGReadWriter2Plugin
	...

And finally, to build your plugin, from MyPlugins/build run:

$ make install

Once the compilation finishes, we can check the results.

As I’m doing this on macOS the resulting directory for the binaries is build/vm/Debug/Pharo.app/Contents/MacOS/Plugins .

And there it is:

$ ls -la build/vm/Debug/Pharo.app/Contents/MacOS/Plugins 
total 83232
drwxr-xr-x  54 seb  staff     1728 Feb 10 19:01 .
drwxr-xr-x   4 seb  staff      128 Feb 10 19:01 ..
-rwxr-xr-x   1 seb  staff   135352 Feb 10 19:01 libB2DPlugin.dylib
-rwxr-xr-x   1 seb  staff    97864 Feb 10 19:01 libBitBltPlugin.dylib
-rwxr-xr-x   1 seb  staff    35952 Feb 10 19:01 libDSAPrims.dylib
-rwxr-xr-x   1 seb  staff    77256 Feb 10 19:01 libFileAttributesPlugin.dylib
-rwxr-xr-x   1 seb  staff    88800 Feb 10 19:01 libFilePlugin.dylib
-rwxr-xr-x   1 seb  staff    22352 Feb 10 19:01 libFloatArrayPlugin.dylib
-rwxr-xr-x   1 seb  staff    17624 Feb 10 19:01 libHelloWorldPlugin.dylib

Let’s see it in action:

$ build/vm/Debug/Pharo.app/Contents/MacOS/Pharo build/vmmaker/image/Pharo10.0.1-0-64bit-0542643.image --interactive

Create an Object subclass: HelloWorld class and add this instance method:

getHelloString

	<primitive: 'primitiveGetHelloString' module: 'HelloWorldPlugin'>
	self primitiveFailed

And test it from this snippet:

Smalltalk vm listLoadedModules.
Smalltalk vm listBuiltinModules.

hello := HelloWorld new.

hello getHelloString. 

With all going well, in your workspace you’ll be getting the string produced by your new primitive.

Notice that is you check listLoadedModules before using getHelloString your plugin is not going to be loaded but if you check after using it for the first time, you’ll find it there showing that Pharo lazy loads the plugins.

Benchmarking

As it gets revealed by now, creating a Pharo Smalltalk plugin requires significant effort, so to get a sense of proportions of what you get for it, lets compare how your plugin performs against a C shared library.

Rust is known to have a general computing performance almost at par with C so I’ve built this simple hello world lib here that can be used to measure this. The README.md file has instructions to build the library.

Go ahead in and build it for release.

$ git clone git@github.com:sebastianconcept/librusthelloworld.git
$ cargo build --release

You will find the built library in:

$ target/release/librusthelloworld.dylib

Create a symlink in the image dir so it can find target/release/librusthelloworld.dylib.

Create RustHelloWorldLibrary as subclass of FFILibrary and add this method in the instance side:

macModuleName
	^ 'librusthelloworld.dylib'

Create HelloWorld as subclass of Object and on the class side add these three methods:

ffiLibrary

	^ RustHelloWorldLibrary

getFFIRustHelloString

	^ self ffiCall: #( char * get_hello_world #( ) )

getHelloString

	<primitive: 'primitiveGetHelloString' module: 'HelloWorldPlugin'>
	self primitiveFailed

With that, you’ll have accessors to the strings that come from the lib in the FFI case and from the primitive of your plugin in the other case:

HelloWorld getFFIRustHelloString.
HelloWorld getHelloString.

Install ABBench for easy comparing bechmarks:

Metacello new
  githubUser: 'emdonahue' project: 'ABBench' commitish: 'master' path: ''; 
  baseline: 'ABBench';
  load.

And run some on these two methods.

Here are the results is showing in a 2.5GHz Intel Quad-core i7 on macOS:

[ HelloWorld getFFIRustHelloString ] bench. 
"'402334.199 per second'"
[ HelloWorld getHelloString ] bench.   
"'22058210.074 per second'"

ABBench bench:[ ABBench 
	a: [HelloWorld getFFIRustHelloString] 
	b: [HelloWorld getHelloString ] ]. 
"B is 3087.45% FASTER than A"

Conclusion

Extending the Pharo Virtual Machine with a plugin is a less-traveled road, but one that offers a lot of potential. Whether you are looking to increase performance or simplify the process of accessing specific functionality, plugins can offer a way to extend Smalltalk in a way that keeps your technology stack simple, elegant and powerful.

The steps involved in producing a plugin are not as straightforward as with FFI, but with a little time and effort, you can create very powerful plugins that add new functionality to your Pharo applications. We hope that by working through the development cycle of a HelloWorldPlugin as described in this article, you can get a sense of the process involved and gain a deeper understanding of the Pharo Virtual Machine.

Overall, extending the Pharo Virtual Machine with a plugin is an excellent way to maximize the potential of Smalltalk, and we hope this article has inspired you to take the next step in your Smalltalk development journey and unlocking potential.

Acknowledgements

A thank you note to the maintainers of the paro-project/pharo-vm, and Guille Polito in particular, which were kind enough to review and merge this modest PR which allows to quickly test that PharoVMMaker is able to generate the source code for the list of plugins that you define.

And a very special mention to Pierre Misse-Chanabier which whom I had many conversations in june 2022 discovering how to get this done. Thanks a lot! None of this work would have been possible without your kind attention and explanations Pierre!

Today, I’m excited to announce a new release of PharoDawnTheme, this dark warm color theme for the Pharo Smalltalk IDE.

This theme is available for Pharo 9 and 10 and can be found in the following URL: https://github.com/sebastianconcept/pharodawntheme.

To install it either in Pharo 9 or 10 you can evaluate this in a playground:

Metacello new 
	baseline: 'PharoDawnTheme';
	repository: 'github://sebastianconcept/PharoDawnTheme';
	load.

PharoDawnTheme is designed to make the development experience in Pharo more enjoyable and efficient. The theme has been optimized for readability and usability, giving developers a more comfortable and efficient development environment resolving some issues found in other themes.

This Dawn theme incorporates modern aesthetics, making your Pharo code look gentle and inviting and removing exaggerated and improperly distracting highlights.

I believe that Pharo developers deserve an environment that gets out of their way and allows them to focus on the goals and concepts they aim to master with their code. With PharoDawnTheme, I’ve tried to provide a theme that enhances the software development experience as much as a color theme can.

We invite you to try out this theme and see how you feel it.

And if you find any issues don’t hesitate in opening one in GitHub.