# Adding "--run" functionality?

**URL:** https://discourse.cmake.org/t/adding-run-functionality/3893
**Category:** Development
**Created:** [August 9, 2021, 3:25pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893 "2021-08-09T15:25:28Z")
**Posts on this page:** 20
**Page:** 1

<div class="post-metadata">

### Author: ![buildSystemPerson](https://discourse.cmake.org/user_avatar/discourse.cmake.org/buildsystemperson/32/2851_2.png) [@buildSystemPerson](https://discourse.cmake.org/u/buildSystemPerson)
#### Post date: [August 9, 2021, 3:25pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/1 "2021-08-09T15:25:28Z")

</div>

For reference [cargo](https://doc.rust-lang.org/book/ch01-03-hello-cargo.html) has a way to just run your app from the command line.

```auto
$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.0 secs
     Running `target/debug/hello_cargo`
Hello, world

```

Perhaps it would be worth it to add this sort of functionality to CMake?

Thoughts?

---

<div class="post-metadata">

### Author: ![hex](https://discourse.cmake.org/user_avatar/discourse.cmake.org/hex/32/363_2.png) [@hex](https://discourse.cmake.org/u/hex)
#### Post date: [August 9, 2021, 9:48pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/2 "2021-08-09T21:48:31Z")

</div>

run is not a default target, but you can easily make one yourself. Note that in your reference it only runs _the_ executable. Which one is run when we have more than one?

---

<div class="post-metadata">

### Author: ![buildSystemPerson](https://discourse.cmake.org/user_avatar/discourse.cmake.org/buildsystemperson/32/2851_2.png) [@buildSystemPerson](https://discourse.cmake.org/u/buildSystemPerson)
#### Post date: [August 10, 2021, 2:45pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/3 "2021-08-10T14:45:03Z")

</div>

If you have more than one you can use `--target` just like CMake already does for building a target.

```auto
# https://cmake.org/cmake/help/latest/manual/cmake.1.html#build-a-project

--target <tgt>..., -t <tgt>...

    Build <tgt> instead of the default target. Multiple targets may be given, separated by spaces.

```

So I guess the syntax for `--run` would borrow heavily from `--build`

---

<div class="post-metadata">

### Author: ![ben.boeckel](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/b/ea5d25/32.png) [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)
#### Post date: [August 10, 2021, 3:05pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/4 "2021-08-10T15:05:20Z")

</div>

The syntax, sure, but there’s more backend work that needs done. Targets don’t “exist” at `cmake --build` time (to CMake) and `--target` just gives the name off to the backend build tool. There’s no actual understanding of what the string means. For example, `cmake --build . --target Source/CMakeFiles/cpack.dir/CPack/cpack.cxx.o` works just fine because `ninja` knows that. So there’s no actual knowledge of what the `--target` argument _means_ at this point and that information would need to be recreated, so this is not a “small” problem.

---

<div class="post-metadata">

### Author: ![buildSystemPerson](https://discourse.cmake.org/user_avatar/discourse.cmake.org/buildsystemperson/32/2851_2.png) [@buildSystemPerson](https://discourse.cmake.org/u/buildSystemPerson)
#### Post date: [August 10, 2021, 3:15pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/5 "2021-08-10T15:15:32Z")

</div>

Gotcha that makes a lot of sense. Yeah now that I think about it, it would be a lot of work to add.

---

<div class="post-metadata">

### Author: ![hex](https://discourse.cmake.org/user_avatar/discourse.cmake.org/hex/32/363_2.png) [@hex](https://discourse.cmake.org/u/hex)
#### Post date: [August 10, 2021, 5:21pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/6 "2021-08-10T17:21:34Z")

</div>

with a target level dependency (run tgt1 depends on build tgt1) the executable exists before execution. The generated build system can understand that without CMake to know.

What happens with `cargo run` if there are multiple targets? Does it run one in particular or abort in error?

---

<div class="post-metadata">

### Author: ![buildSystemPerson](https://discourse.cmake.org/user_avatar/discourse.cmake.org/buildsystemperson/32/2851_2.png) [@buildSystemPerson](https://discourse.cmake.org/u/buildSystemPerson)
#### Post date: [August 10, 2021, 6:02pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/7 "2021-08-10T18:02:56Z")

</div>

[Target Selection](https://doc.rust-lang.org/cargo/commands/cargo-run.html#target-selection)

```auto
When no target selection options are given, cargo run will run the binary target. If there are multiple binary targets, you must pass a target flag to choose one. Or, the default-run field may be specified in the [package] section of Cargo.toml to choose the name of the binary to run by default.
--bin nameRun the specified binary.--example nameRun the specified example.

```

---

<div class="post-metadata">

### Author: ![ferdnyc](https://discourse.cmake.org/user_avatar/discourse.cmake.org/ferdnyc/32/267_2.png) [@ferdnyc](https://discourse.cmake.org/u/ferdnyc)
#### Post date: [August 16, 2021, 8:08am UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/8 "2021-08-16T08:08:28Z")

</div>

It strikes me that Cargo and CMake are very different things, in this context.

`cargo` is a packaging tool (with compiler integration) for a single language (Rust). Other analogous tools: `npm` (Node.js), `pip` (Python), `gem` (Ruby), etc.

- `cargo run` exists because most Rust packages contain one or more binary targets, defined in their own documentation as “executable programs that can be run after being compiled.” Its metadata format (`Cargo.toml`) allows tagging a binary target as `default-run`.

- `npm run` is actually an alias for `npm run-script`, which works with the `scripts` object of its JSON metadata format (`package.json`). There, arbitrary commands can be named as “scripts”, runnable both automatically at certain stages of the package lifecycle, or manually using `npm run`. This is necessary because _no_ JS packages are standalone executable binaries. `npm` is therefore an overachiever on this front.

- `pip run` does not exist, because most Python modules are not executable as such, they are scripts to run through an interpreter, and many are library packages meant to be called from other Python code rather than directly.  
Some packages do install one or more “entry-points”, scripts used to launch a module, but even those require an installed package. (If a module is runnable from the build directory, those semantics are for the most part up to the author.) An entry point script or `python3 -m <module>` is the preferred way to launch a runnable module.

- `gem run` does not exist, because most Ruby gems are not executable as such, they are scripts to be run through an interpreter. (etc, etc.)

CMake, OTOH, is a build system generator that supports (in theory) building _any_ type of output, for _any_ platform, in _any_ source language. While C/C++/Fortran are the most common, and while CMake does have the concept of an “executable target”, the run semantics of that target are impossibly diverse:

- It could be cross-compiled, in which case it’s not runnable on the current host platform
- It may be a binary component of a macOS application Bundle, in which case it requires a particular filesystem layout from which to be run
- It may be a Windows executable, in which case it may require a specific `%PATH%` environment variable and/or the consolidation of `.dll` dependencies in order to be runnable.
- It may have been compiled using `SKIP_BUILD_RPATH`, `BUILD_WITH_INSTALL_RPATH`, or other options that may render it non-executable from the build directory.
- It may be a Qt program, and require further configuration of plugin dirs or other paths via a `qt.conf` file in order to be properly executable.

The notion of “running the results of a CMake build” really isn’t as concrete a notion as “running a compiled Rust binary”, not to the point where it would be as easy (or as useful) to generalize it into a built-in utility command. But, like @hex suggested, there’s certainly nothing stopping you from using `add_custom_target()` to create a `run` target, with `COMMAND` arguments defining how your executable(s) should be run (much like `npm`'s `scripts` definitions), and then using `cmake --build <builddir> --target run` to run it.

---

<div class="post-metadata">

### Author: ![ferdnyc](https://discourse.cmake.org/user_avatar/discourse.cmake.org/ferdnyc/32/267_2.png) [@ferdnyc](https://discourse.cmake.org/u/ferdnyc)
#### Post date: [August 22, 2021, 9:26pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/9 "2021-08-22T21:26:31Z")

</div>

Hah! Interesting, and very coincidental.

Qt Creator, like many IDEs, _does_ have a “run project” feature in their build system, so they had the same problem of not being able to automatically detect what exactly should be run, when the user clicks “Run”.

For Creator 5 (which brings greatly expanded CMake support across the board), they’ve settled on using a target `FOLDER` property, set to a specific magic value of `"qtc_runnable"`, to designate the default run target.

So,

```cmake
set_target_properties(main_executable PROPERTIES FOLDER "qtc_runnable")

```

I have to imagine some sort of UI for managing that property would be coming along eventually, because applying it in the source like that is kind of magical and weird.

Details in the [recent blog post](https://www.qt.io/blog/qt-creator-5-cmake-projects-update) (see the “Selecting a default run target” heading.)

---

<div class="post-metadata">

### Author: ![hex](https://discourse.cmake.org/user_avatar/discourse.cmake.org/hex/32/363_2.png) [@hex](https://discourse.cmake.org/u/hex)
#### Post date: [August 22, 2021, 10:58pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/10 "2021-08-22T22:58:19Z")

</div>

thank you for bringing this up. In lack of anything else i might just adopt this name. The configuration should not be tight to the source tree, though. Offering an automatic setup can be convenient but also makes the user _expect_ such convenience for every project, even for projects where it doesn’t make sense. A sane default selection for a target is not always possible, and opinionated at best.

Making it a user setting is much better, which could be tied to the IDE project, or CMake build tree.

---

<div class="post-metadata">

### Author: ![hsattler](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/h/59ef9b/32.png) [@hsattler](https://discourse.cmake.org/u/hsattler)
#### Post date: [August 22, 2021, 11:35pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/11 "2021-08-22T23:35:50Z")

</div>

Sorry to say that but what a dumb idea by QtCreator developers thinking that they are the only used IDE in a project to capture target’s FOLDER property like that.

---

<div class="post-metadata">

### Author: ![hex](https://discourse.cmake.org/user_avatar/discourse.cmake.org/hex/32/363_2.png) [@hex](https://discourse.cmake.org/u/hex)
#### Post date: [August 22, 2021, 11:52pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/12 "2021-08-22T23:52:06Z")

</div>

they use a prefix to avoid conflicts and the property can be read before written

---

<div class="post-metadata">

### Author: ![ben.boeckel](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/b/ea5d25/32.png) [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)
#### Post date: [August 22, 2021, 11:57pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/13 "2021-08-22T23:57:29Z")

</div>

Well, sure. But I might want to use `FOLDER` for my organization. Why commandeer an existing property instead of making a new one like `_qtc_runnable` that is set to `TRUE` or `FALSE`?

---

<div class="post-metadata">

### Author: ![ben.boeckel](https://discourse.cmake.org/letter_avatar_proxy/v4/letter/b/ea5d25/32.png) [@ben.boeckel](https://discourse.cmake.org/u/ben.boeckel)
#### Post date: [August 23, 2021, 12:00am UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/14 "2021-08-23T00:00:46Z")

</div>

> [@ferdnyc](#):
>
> Details in the [recent blog post](https://www.qt.io/blog/qt-creator-5-cmake-projects-update) (see the “Selecting a default run target” heading.)

Can someone please comment on that blog post that using `FOLDER` is terrible? I’ll go file an issue I guess…

---

<div class="post-metadata">

### Author: ![craig.scott](https://discourse.cmake.org/user_avatar/discourse.cmake.org/craig.scott/32/20_2.png) [@craig.scott](https://discourse.cmake.org/u/craig.scott)
#### Post date: [August 23, 2021, 12:04am UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/15 "2021-08-23T00:04:06Z")

</div>

I’ve already raised this internally with the Qt Creator team.

---

<div class="post-metadata">

### Author: ![leha-bot](https://discourse.cmake.org/user_avatar/discourse.cmake.org/leha-bot/32/921_2.png) [@leha-bot](https://discourse.cmake.org/u/leha-bot)
#### Post date: [August 24, 2021, 10:32am UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/16 "2021-08-24T10:32:22Z")

</div>

Hello, Craig, what do you think about adding another `property` (like `PROJECT_RUN_TARGET`)? As the MSVC, xcode supports running specified target and this option is stored in its project files.  
The CMake-based IDEs like Qt Creator could simply fall back into this property and use it.  
Thanks for attention.

---

<div class="post-metadata">

### Author: ![craig.scott](https://discourse.cmake.org/user_avatar/discourse.cmake.org/craig.scott/32/20_2.png) [@craig.scott](https://discourse.cmake.org/u/craig.scott)
#### Post date: [August 24, 2021, 9:53pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/17 "2021-08-24T21:53:22Z")

</div>

One of the things identified by the internal discussions was that most target properties are not available through the file API. The reason the FOLDER property was used is that it does have a dedicated field in the file API, so it can be read by IDEs like Qt Creator. One would likely need to extend the file API to support queries asking for specific properties to avoid that. If that were implemented, then I guess having a “blessed” property that is expected to act as this meaning for all IDEs would make sense, but a look at how the different IDEs implement or support this sort of feature and what such a property would need to represent would have to occur first.

---

<div class="post-metadata">

### Author: ![hex](https://discourse.cmake.org/user_avatar/discourse.cmake.org/hex/32/363_2.png) [@hex](https://discourse.cmake.org/u/hex)
#### Post date: [August 24, 2021, 10:42pm UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/18 "2021-08-24T22:42:58Z")

</div>

is it desired / necessary to use CMake for this? The complete list of existing targets is available to the IDE. It could provide the necessary GUI elements to the user to decide which targets are eligible for a run target, and the set of targets enabled for run. These preferences could be tied to the GUI instead of the configured CMake project.

---

<div class="post-metadata">

### Author: ![ferdnyc](https://discourse.cmake.org/user_avatar/discourse.cmake.org/ferdnyc/32/267_2.png) [@ferdnyc](https://discourse.cmake.org/u/ferdnyc)
#### Post date: [August 25, 2021, 8:26am UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/19 "2021-08-25T08:26:05Z")

</div>

> [@hex](#):
>
> is it desired / necessary to use CMake for this?

I don’t know about “necessary”, but I can see how it would be desirable, in particular for people who are creating CMake projects that will be built and run by others.

I can certainly see where it would be particularly helpful in an education/tutorial context. There’s certainly an appeal to being able to import a Git repository into Qt Creator, and have a default assignment for the Run target already present. (Without having to define yet another proprietary/non-standard metadata file with which to embed that information into the source tree.)

---

<div class="post-metadata">

### Author: ![hex](https://discourse.cmake.org/user_avatar/discourse.cmake.org/hex/32/363_2.png) [@hex](https://discourse.cmake.org/u/hex)
#### Post date: [August 25, 2021, 9:09am UTC](https://discourse.cmake.org/t/adding-run-functionality/3893/20 "2021-08-25T09:09:52Z")

</div>

the majority of tutorials only have a single target of type executable. When there are options, pressing run could ask for choosing one once at first launch. This can certainly cover a large chunk of use cases already.

To cover all remaining cases, the `vendor` field in [CMake presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html) seems more suitable for these setup than fileAPI, because, as i currently understand it, Qt Creator is itself handling the run target. There is no standard CMake implementation of a run target.

[Next page](https://discourse.cmake.org/t/adding-run-functionality/3893.md?page=2)