copes 1.1.1

A tool that identifies executable files used in automatic CoreCtrl profiles
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

# CoreCtrl Process Executable Solver CLI tool
`copes` is a command line utility that identifies executable files used in [automatic CoreCtrl profiles](https://gitlab.com/corectrl/corectrl/-/wikis/How-profiles-works).

## Rust version support
The minimum supported Rust toolchain version is currently **Rust 1.77**.

## Compilation
To build the application, the following software must be installed in your system:
- A [Rust](https://www.rust-lang.org/) toolchain. You can easily install it using [rustup.rs](https://rustup.rs/) or your distribution package manager.
- `clang` compiler and a linker (`ld`, `lld`... your choice).

Run `cargo build -r` on the project root directory. The program executable will be placed in the `target/release` directory.

## Installation
If you don't want to manually clone the repository and build the program by yourself, you can install it running the following command:

    cargo install copes

## Runtime dependencies
Under the hood, this program uses the [process events connector kernel interface](https://github.com/torvalds/linux/commit/9f46080c41d5f3f7c00b4e169ba4b0b2865258bf). Therefore, a Linux kernel compiled with `CONFIG_PROC_EVENTS` option enabled is required.

## Usage
If you are using Linux 6.5 or earlier versions, you must run this program with root privileges. Otherwise, you can skip the `sudo` part on the following commands if you only want to monitor non-privileged processes.

If you manually cloned and compiled the application, run:

    sudo target/release/copes

Otherwise, run:

    sudo copes

By default, this utility shows the process event (either `Exec` or `Exit`), the process `PID` and the executable file for which the process was started. Executable file names are resolved in a similar way CoreCtrl does.

Press `Control + c` to quit the program.

## Options

    -c              Print the process command line
        --no-color  Do not colorize output
    -h, --help      Print help
    -V, --version   Print version

## Finding the right executable file for an automatic CoreCtrl profile
Suppose that you have created an automatic profile, but for some reason, it's not activated when you start the program for which you created the profile.

The following list outlines the common causes of this issue:
- The program only runs for a short period of time. This behaviour is very common on games, where a launcher is used to starts the game. For example, `game.exe` is a launcher that starts a process for `game_dx11.exe` and then exits.
- The program executable name differs from the name you used as the executable name on the profile. Be aware that file names are **case sensitive**.
- The program is written using an interpreted language (like bash script or python), which currently is not handled by CoreCtrl.

Another cause could be the kernel you are running was compiled with the `CONFIG_PROC_EVENTS` option disabled. If you run this utility and see no output after launching some programs, then it's probable that this is the cause of the issue. You can verify it by searching for such option on the kernel configuration file. Please, refer to your distribution documentation to locate such file on your file system.

You can check any of the aforementioned causes by starting this utility **before** launching the application associated to the profile.

### Example
Running the program produces the following output when launching the popular game *Control*:

    ...
    Exec(24138) tabtip.exe
    Exec(24141) Control.exe
    Exec(24147) Control_DX12.exe
    Exit(24141) Control.exe

At this point the game is running. Notice that `Control.exe` is just a launcher whose only purpose is to start the true game executable (`Control_DX12.exe`) and that its process (`24141`) exits just after starting the other one (`24147`).

When the game is quit:

    ...
    Exit(24147) Control_DX12.exe
    Exit(24138) tabtip.exe
    Exit(24133) explorer.exe
    Exit(24062) winedevice.exe
    Exit(24071) winedevice.exe
    Exit(24084) plugplay.exe
    Exit(24090) svchost.exe
    Exit(24107) rpcss.exe
    Exit(24053) steam.exe
    ...

Notice how the game process (`24147`), started for the executable `Control_DX12.exe` exits at this point.

In this case, `Control_DX12.exe` must be used as the executable name on the CoreCtrl profile. Otherwise, the profile won't be active while playing the game.

## License

`copes` is licensed under the [GNU General Public License v3.0](LICENSE). Permissions of this copyleft license are conditioned on making available complete source code of licensed works and modifications, which include larger works using a licensed work, under the same license. Copyright and license notices must be preserved. Contributors provide an express grant of patent rights.

## Contribution
Please, read the [CONTRIBUTING](../CONTRIBUTING.md) guide for more information about how to get started.

Any contribution intentionally submitted for inclusion in the work by you shall be licensed under the GNU General Public License v3.0 (GPL-3.0). It is required to add a boilerplate copyright notice to the top of each file:

    // SPDX-License-Identifier: GPL-3.0-or-later
    // Copyright {year} {person OR org} <{email}>