Sublime Forum

How does "build with" command work?

#1

I’m trying to understand how the “build with” command works behind the curtains (either in automatic mode or not). As far as I’ve seen, each time you use “build with” something is persisted somewhere so that build-system will execute each time you “build” with ctrl+b, it seems this is persisted at a project level and at window level.

But I don’t understand very well what’s doing so, could anyone explain how does “build with” command work? Is there any way to know which is the “active” build system at any time? Is there any way to reset its behaviour so when i press again ctrl+b a new quick_panel with the available build_systems for that selector is spawn?

To be honest, the docs are a little bit short when it comes to explain the magic of this command and I don’t see the source code anywhere in the default package. When I do sublime.log_commands(True) i can see BuildCommand.run(select=True) is called and also can see the contents of the quick_panel showing the available build_systems for that selector, but that’s it… that doesn’t clarify me how all this works :confused:

Thanks in advance.

1 Like
#2

You can observe most of the build functionality by enabling sublime.log_commands(True).

“build with” basically runs the build command with select: false, which I is the default anyway iirc. Selecting a build in the ctrl+b panel would, however, run the command with select: true, which stores the selected build system and variant.

(I should document this at some point. It’s been almost two years now.)

1 Like
#3

Thanks for the answer, although that doesn’t clarify any of the questions i’ve asked above :wink: . Btw, when you said:

“build with” basically runs the build command with select: false, which I is the default anyway iirc.

I guess you meant “true”… read again my initial post, at least that’s what i see when using sublime.log_commands(True).

Anyway, this command is really handy one but at the same time is quite tricky for the user to know what’s going on… if at least there would have a way to query through the API to know what’s modified it’d be easy to know what’s going on here.

@wbond Sorry to bother pinging you, could you bring some light about this one? Thanks.

1 Like
#4

Is your “build with” the one that opens with ctrl+shift+b? Because I was thinking of the one-shot build commands available on the command palette.

I’m not at a pc to confirm right now.

Ah well, it appears I skipped a few questions. As mentioned, ctrl+shift+b will explicitly reopen the panel to select a build system. I’m not sure whether the selection is global, per selector/match, per window or a mix of those. I don’t use different build systems often enough to notice.

1 Like
#5

Yeah, in the Default\Default (Windows).sublime-keymap i’ve got these ones:

{ "keys": ["f7"], "command": "build" },
{ "keys": ["ctrl+b"], "command": "build" },
{ "keys": ["ctrl+shift+b"], "command": "build", "args": {"select": true} },
{ "keys": ["ctrl+break"], "command": "cancel_build" },

In the User\Default (Windows).sublime-keymap i’ve got these ones:

{
    "keys": ["ctrl+alt+b"],
    "command": "show_overlay",
    "args": {
        "overlay": "command_palette",
        "text": "Build With: "
    }
}

Anyway, I can see now you’ve realized about my questions :wink:

1 Like
#6

The current build variant is persisted in the session (per window) (see the Local/Session.sublime_session file).

AFAIK, no.

Not that I know of (assuming you mean on-demand, not just rebinding Ctrl+B).

1 Like
#7

Interesting, thanks! I wasn’t aware of this file Session.sublime_session.

As you said, the list of windows will contain the whole information of each window opened per session, and the key affected by the build_with command is build_system, which is persisted onto the file once the session is terminated. In fact, I assume the whole sublime_session is hold on memory and is dumped once Sublime session is finished (normally or abnormally), the fact there isn’t any function to query these settings must mean there isn’t any way to know the active build_system per window.

Btw, do you know what’s the meaning of pinned_build_system and build_varint, yeah… i said build_varint and not build_variant , that must be a bug :slight_smile: . Asking this cos I’m still trying to understand on which cases the quick_panel offering the variants is shown once you press ctrl+b… cos i got a window where build_system:"" and when i press ctrl+b a certain variant (out of 3) is executed without giving me the choice through the quick_panel, i don’t get it :confused:

1 Like
#8

Yea, I noticed the misspelling, too. I believe pinned_build_system is the build system you choose from Tools > Build System when it is not “Automatic”. build_varint is the variant selected when you run Tools > Build With… (Ctrl+Shift+B), or it is empty if no variant is selected.

Sublime will ask you to choose a build variant when you run a build system for the first time. It will remember your choice as the default in the future. I’m not sure what it takes to get Sublime to forget your choice, perhaps if you modify a build-system definition and it has to reload?

1 Like
#9

Sublime Text remembers the last choice you made for a given set of build options, and uses that when you press Ctrl+B.

Options in this context means the set of relevant build systems, which varies based on the syntax of the current file, if there’s a Makefile in the current directory, etc. Basically the set of valid build systems at this point in time.

When you press Ctrl+B, if it doesn’t have a last choice from the current set of options, then it prompts you with the list of options, and will remember the choice. To change your choice, press Ctrl+Shift+B, and it’ll both explicitly prompt you, and remember that choice, too.

3 Likes
#10

Thanks for the explanation.

I think I kind of understand now, that’s quite the smart system. So that was the meaning of the build_system_choices key… it establishes a relationship between a “set” of build_systems and a choice, i.e, let’s say a sublime-session looks like this:

build_system_choices = [
    [[b0,b0],[b0]],
    [[b0,b1],[b1]],
    [[b1,b0],[b0]],
    [[b1,b1],[b1]]
]

Now, let’s say I try to build a file which can use (list populated by using selector, syntax, …) [b0,b1], if i’m not mistaken the build_system b1 would be the choice on that particular set/session. But if you decided to build_with b0 for that particular set of build_systems, the sublime-session would become like this:

build_system_choices = [
    [[b0,b0],[b0]],
    [[b0,b1],[b0]],
    [[b1,b0],[b0]],
    [[b1,b1],[b1]]
]

Is this correct?

Last question cos more or less I’ve understood the basics of the logic behind this… I’m assuming a set of options [b0,b1] is different than [b1,b0], right?

Also, I’ve noticed if i delete a sublime-session and I load a sublime-project, for some reason the sublime-session will become quite meaty, i guess the build_system_choices will be restorerd from some backup file? I’m asking you this cos I’m curious about whether i can reset the behaviour so my build_system_choices can be set to a factory-empty state again.

0 Likes
#11

Build systems are consistently ordered, so in your example it would always be [b0,b1], [b1,b0] would never be encountered.

If you’re working with a project, then the session state for the project is stored in the .sublime-workspace file, and not in the global Session.sublime-session file

0 Likes