Skip to content

Commit

Permalink
Closes #100, breaks up the README
Browse files Browse the repository at this point in the history
  • Loading branch information
@xxxserxxx
xxxserxxx committed Jun 2, 2020
1 parent dcec8a5 commit d6be10b
Show file tree
Hide file tree
Showing 6 changed files with 171 additions and 151 deletions.
18 changes: 13 additions & 5 deletions .github/workflows/release.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,13 @@ jobs:
event-type: my-release
client-payload: '{"tag": "${{ steps.tag_name.outputs.tag }}"}'

- name: Update and inform Homebrew
uses: dawidd6/action-homebrew-bump-formula@v3
with:
token: ${{ secrets.homebrew }}
formula: gotop
revision: ${{ steps.tag_name.outputs.tag }}

- name: Update Arch AURs
uses: peter-evans/repository-dispatch@v1
with:
Expand All @@ -30,12 +37,13 @@ jobs:
event-type: my-release
client-payload: '{"tag": "${{ steps.tag_name.outputs.tag }}"}'

- name: Update and inform Homebrew
uses: dawidd6/action-homebrew-bump-formula@v3
- name: Trigger extensions build
uses: peter-evans/repository-dispatch@v1
with:
token: ${{ secrets.homebrew }}
formula: gotop
revision: ${{ steps.tag_name.outputs.tag }}
token: ${{ secrets.REPO_ACCESS_TOKEN }}
repository: xxxserxxx/gotop-builder
event-type: my-release
client-payload: '{"tag": "${{ steps.tag_name.outputs.tag }}"}'

- name: Update current release badge
shell: bash
Expand Down
164 changes: 18 additions & 146 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,22 +36,29 @@ If you install gotop by hand, or you download or create new layouts or colorsche
- **Prebuilt binaries**: Binaries for most systems can be downloaded from [the github releases page](https://github.com/xxxserxxx/gotop/releases). RPM and DEB packages are also provided.
- **Source**: This requires Go >= 1.14. `go get -u github.com/xxxserxxx/gotop/cmd/gotop`

### Console Users Note
### Extension builds

An evolving mechanism in gotop are extensions. This is designed to allow gotop to support feature sets that are not universally needed without blowing up the application for average users with usused features. Examples are support for specific hardware sets like video cards, or things that are just obviously not a core objective of the application, like remote server monitoring.

The path to these extensions is a tool called [gotop-builder](https://github.com/xxxserxxx/gotop-builder). It is easy to use and depends only on having Go installed. You can read more about it on the project page, where you can also find binaries for Linux that have *all* extensions built in. If you want less than an all-inclusive build, or one for a different OS/architecture, you can use gotop-builder itself to create your own.


### Console Users

gotop requires a font that has braille and block character Unicode code points; some distributions do not provide this. In the gotop repository is a `pcf` font that has these points, and setting this font may improve how gotop renders in your console. To use this, run these commands:

```shell
$ curl -O -L https://raw.githubusercontent.com/xxxserxxx/gotop/master/fonts/Lat15-VGA16-braille.psf
$ setfont Lat15-VGA16-braille.psf
curl -O -L https://raw.githubusercontent.com/xxxserxxx/gotop/master/fonts/Lat15-VGA16-braille.psf
setfont Lat15-VGA16-braille.psf
```

### Building

This is the download & compile approach.

gotop should build with most versions of Go. If you have a version other than 1.14 installed, remove the `go` line at the end of `go.mod`.
gotop should build with most versions of Go. If you have a version other than 1.14 installed, remove the `go` line at the end of `go.mod` and it should work.

```
```shell
git clone https://github.com/xxxserxxx/gotop.git
cd gotop
sed -i '/^go/d' go.mod # Do this if you have go != 1.14
Expand All @@ -71,149 +78,14 @@ In addition to the key bindings, the mouse can be used to control the process li
- click to select process
- mouse wheel to scroll through processes

## Config file
Most command-line settings can be persisted into a configuration file. The config file is named `gotop.conf` and can be located in several places. The first place gotop will look is in the current directory; after this, the locations depend on the OS and distribution. On Linux using XDG, for instance, the home location of `~/.config/gotop/gotop.conf` is the second location. The last location is a system-wide global location, such as `/etc/gotop/gotop.conf`. The `-h` help command will print out all of the locations, in order. Command-line options override values in any config files, and only the first config file found is loaded.
A configuration file can be created using the `--write-config` command-line argument. This will try to place the config file in the home config directory (the second location), but if it's unable to do so it'll write a file to the current directory.
Config file changes can be made by combining command-line arguments with `--write-config`. For example, to persist the `solarized` theme, call:
```
gotop -c solarized --write-config
```
### Colorschemes
gotop ships with a few colorschemes which can be set with the `-c` flag followed by the name of one. You can find all the colorschemes in the [colorschemes folder](./colorschemes).
To make a custom colorscheme, check out the [template](./colorschemes/template.go) for instructions and then use [default.json](./colorschemes/default.json) as a starter. Then put the file at `~/.config/gotop/<name>.json` and load it with `gotop -c <name>`. Colorschemes PR's are welcome!
To list all built-in color schemes, call:
```
gotop --list colorschemes
```
### Layouts
gotop can parse and render layouts from a specification file. The format is
intentionally simple. The amount of nesting levels is limited. Some examples
are in the `layouts` directory; you can try each of these with, e.g.,
`gotop --layout-file layouts/procs`. If you stick your layouts in
`$XDG_CONFIG_HOME/gotop`, you can reference them on the command line with the
`-l` argument, e.g. `gotop -l procs`.
The syntax for each widget in a row is:
```
(rowspan:)?widget(/weight)?
```
and these are separated by spaces.
1. Each line is a row
2. Empty lines are skipped
3. Spaces are compressed (so you can do limited visual formatting)
4. Legal widget names are: cpu, disk, mem, temp, batt, net, procs
5. Widget names are not case sensitive
4. The simplest row is a single widget, by name, e.g. `cpu`
5. **Weights**
1. Widgets with no weights have a weight of 1.
2. If multiple widgets are put on a row with no weights, they will all have
the same width.
3. Weights are integers
4. A widget will have a width proportional to its weight divided by the
total weight count of the row. E.g.,
```
cpu net
disk/2 mem/4
```
The first row will have two widgets: the CPU and network widgets; each
will be 50% of the total width wide. The second row will have two
widgets: disk and memory; the first will be 2/6 ~= 33% wide, and the
second will be 5/7 ~= 67% wide (or, memory will be twice as wide as disk).
9. If prefixed by a number and colon, the widget will span that number of
rows downward. E.g.
```
mem 2:cpu
net
```
Here, memory and network will be in the same row as CPU, one over the other,
and each half as high as CPU; it'll look like this:
```
+------+------+
| Mem | |
+------+ CPU |
| Net | |
+------+------+
```
10. Negative, 0, or non-integer weights will be recorded as "1". Same for row
spans.
11. Unrecognized widget names will cause the application to abort.
12. In rows with multi-row spanning widgets **and** weights, weights in
lower rows are ignored. Put the weight on the widgets in that row, not
in later (spanned) rows.
13. Widgets are filled in top down, left-to-right order.
14. The larges row span in a row defines the top-level row span; all smaller
row spans constitude sub-rows in the row. For example, `cpu mem/3 net/5`
means that net/5 will be 5 rows tall overall, and mem will compose 3 of
them. If following rows do not have enough widgets to fill the gaps,
spacers will be used.
Yes, you're clever enough to break the layout algorithm, but if you try to
build massive edifices, you're in for disappointment.
To list all built-in color schemes, call:
```
gotop --list layouts
```
### Device filtering
Some devices have quite a number of data points; on OSX, for instance, there are dozens of temperature readings. These can be filtered through a configuration file. There is no command-line argument for this filter.
The list will grow, but for now the only device that supports filtering is the temperature widget. The configuration entry is called `temperature`, and it contains an exact-match list of comma-separated values with no spaces. To see the list of valid values, run gotop with the `--list devices` command. Gotop will print out the type of device and the legal values. For example, on Linux:
```
$ gotop --list devices
Temperatures:
acpitz
nvme_composite
nvme_sensor1
nvme_sensor2
pch_cannonlake
coretemp_packageid0
coretemp_core0
coretemp_core1
coretemp_core2
coretemp_core3
ath10k_hwmon
```
You might then add the following line to the config file. First, find where gotop looks for config files:
```
$ gotop -h | tail -n 6
Colorschemes & layouts that are not built-in are searched for (in order) in:
/home/USER/workspace/gotop.d/gotop, /home/USER/.config/gotop, /etc/xdg/gotop
The first path in this list is always the cwd. The config file
'gotop.config' can also reside in one of these directories.

Log files are stored in /home/ser/.cache/gotop/errors.log
```
So you might use `/home/YOU/.config/gotop.conf`, and add (or modify) this line:
```
temperatures=acpitz,coretemp_core0,ath10k_hwmon
```
This will cause the temp widget to show only four of the eleven temps.
For more information on other topics, see:

### CLI Options
- [Layouts](docs/layouts.md)
- [Configuration](docs/configuration.md)
- [Color schemes](docs/colorschemes.md)
- [Device filtering](docs/devices.md)
- [Extensions](docs/extensions.md)

Run `gotop -h` to see the list of all command line options.

## More screen shots

Expand Down
12 changes: 12 additions & 0 deletions docs/colorschemes.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Colorschemes

gotop ships with a few colorschemes which can be set with the `-c` flag followed by the name of one. You can find all the colorschemes in the [colorschemes folder](./colorschemes).

To make a custom colorscheme, check out the [template](./colorschemes/template.go) for instructions and then use [default.json](./colorschemes/default.json) as a starter. Then put the file at `~/.config/gotop/<name>.json` and load it with `gotop -c <name>`. Colorschemes PR's are welcome!

To list all built-in color schemes, call:

```
gotop --list colorschemes
```

12 changes: 12 additions & 0 deletions docs/configuration.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# Config file

Most command-line settings can be persisted into a configuration file. The config file is named `gotop.conf` and can be located in several places. The first place gotop will look is in the current directory; after this, the locations depend on the OS and distribution. On Linux using XDG, for instance, the home location of `~/.config/gotop/gotop.conf` is the second location. The last location is a system-wide global location, such as `/etc/gotop/gotop.conf`. The `-h` help command will print out all of the locations, in order. Command-line options override values in any config files, and only the first config file found is loaded.

A configuration file can be created using the `--write-config` command-line argument. This will try to place the config file in the home config directory (the second location), but if it's unable to do so it'll write a file to the current directory.

Config file changes can be made by combining command-line arguments with `--write-config`. For example, to persist the `solarized` theme, call:

```
gotop -c solarized --write-config
```

37 changes: 37 additions & 0 deletions docs/devices.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
# Device filtering

Some devices have quite a number of data points; on OSX, for instance, there are dozens of temperature readings. These can be filtered through a configuration file. There is no command-line argument for this filter.

The list will grow, but for now the only device that supports filtering is the temperature widget. The configuration entry is called `temperature`, and it contains an exact-match list of comma-separated values with no spaces. To see the list of valid values, run gotop with the `--list devices` command. Gotop will print out the type of device and the legal values. For example, on Linux:

```
$ gotop --list devices
Temperatures:
acpitz
nvme_composite
nvme_sensor1
nvme_sensor2
pch_cannonlake
coretemp_packageid0
coretemp_core0
coretemp_core1
coretemp_core2
coretemp_core3
ath10k_hwmon
```
You might then add the following line to the config file. First, find where gotop looks for config files:
```
➜ gotop --list paths
Loadable colorschemes & layouts, and the config file, are searched for, in order:
/home/ser/workspace/gotop.d/gotop
/home/ser/.config/gotop
/etc/xdg/gotop
The log file is in /home/ser/.cache/gotop/errors.log
```
So you might use `${HOME}/.config/gotop/gotop.conf`, and add (or modify) this line:
```
temperatures=acpitz,coretemp_core0,ath10k_hwmon
```
This will cause the temp widget to show only four of the eleven temps.

79 changes: 79 additions & 0 deletions docs/layouts.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Layouts

gotop can parse and render layouts from a specification file. The format is
intentionally simple. The amount of nesting levels is limited. Some examples
are in the `layouts` directory; you can try each of these with, e.g.,
`gotop --layout-file layouts/procs`. If you stick your layouts in
`$XDG_CONFIG_HOME/gotop`, you can reference them on the command line with the
`-l` argument, e.g. `gotop -l procs`.

The syntax for each widget in a row is:
```
(rowspan:)?widget(/weight)?
```
and these are separated by spaces.

1. Each line is a row
2. Empty lines are skipped
3. Spaces are compressed (so you can do limited visual formatting)
4. Legal widget names are: cpu, disk, mem, temp, batt, net, procs
5. Widget names are not case sensitive
4. The simplest row is a single widget, by name, e.g. `cpu`
5. **Weights**
1. Widgets with no weights have a weight of 1.
2. If multiple widgets are put on a row with no weights, they will all have
the same width.
3. Weights are integers
4. A widget will have a width proportional to its weight divided by the
total weight count of the row. E.g.,

```
cpu net
disk/2 mem/4
```
The first row will have two widgets: the CPU and network widgets; each
will be 50% of the total width wide. The second row will have two
widgets: disk and memory; the first will be 2/6 ~= 33% wide, and the
second will be 5/7 ~= 67% wide (or, memory will be twice as wide as disk).
9. If prefixed by a number and colon, the widget will span that number of
rows downward. E.g.
```
mem 2:cpu
net
```
Here, memory and network will be in the same row as CPU, one over the other,
and each half as high as CPU; it'll look like this:
```
+------+------+
| Mem | |
+------+ CPU |
| Net | |
+------+------+
```
10. Negative, 0, or non-integer weights will be recorded as "1". Same for row
spans.
11. Unrecognized widget names will cause the application to abort.
12. In rows with multi-row spanning widgets **and** weights, weights in
lower rows are ignored. Put the weight on the widgets in that row, not
in later (spanned) rows.
13. Widgets are filled in top down, left-to-right order.
14. The larges row span in a row defines the top-level row span; all smaller
row spans constitude sub-rows in the row. For example, `cpu mem/3 net/5`
means that net/5 will be 5 rows tall overall, and mem will compose 3 of
them. If following rows do not have enough widgets to fill the gaps,
spacers will be used.
Yes, you're clever enough to break the layout algorithm, but if you try to
build massive edifices, you're in for disappointment.
To list all built-in color schemes, call:
```
gotop --list layouts
```

0 comments on commit d6be10b

Please sign in to comment.