diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/bashtop.md | 7 | ||||
| -rw-r--r-- | docs/colorschemes.md | 12 | ||||
| -rw-r--r-- | docs/configuration.md | 12 | ||||
| -rw-r--r-- | docs/devices.md | 37 | ||||
| -rw-r--r-- | docs/layouts.md | 79 | ||||
| -rw-r--r-- | docs/releasing.md | 37 |
6 files changed, 165 insertions, 19 deletions
diff --git a/docs/bashtop.md b/docs/bashtop.md new file mode 100644 index 0000000..d985874 --- /dev/null +++ b/docs/bashtop.md @@ -0,0 +1,7 @@ +# A comment about bashtop + +Among tops, bashtop deserves extra recognition. It's one of the most impressive pieces of work I've encountered, on a couple of levels. For one, it is full of interesting, uncommon, and *useful* features. For another, it was accomplished with pure bash. In other words, it does far more with a far less sophisticated tool than it's peers. bashtop has a thoughtful and intelligent design of how information is presented. It has an attractive interface, with features like greyscale coloring in the process list that draw your eye to the heaviest processes. It's a beautiful, pleasant terminal UI, and I haven't yet seen anything as good, even among GUIs with all of the tools at their disposal. + +bashtop is also utterly insane. It is a single, 140KB, 3,508-line bash script. The author claims to be doing a rewrite in Python, but that will never undo the admiration I have for what he accomplished with bash. Respect, Aristocratos. + +If bashtop is so great, then why am I maintaining gotop? Two reasons. First, because I can't contribute to bashtop. I'm not that good with bash - not at the astronomic level Aristocratos is working at - and I really don't *want* to be that good. I've been there, and bash -- while universal, very useful, and probably my go-to scripting tool -- is hell to maintain at any scale. 3,500 lines of bash is a headache, no matter how you slice it. And second, because it's relatively heavy on the CPU for a tool that's supposed to sit off to the side and be glanced at occasionally. But it is an inspiration, and I sincerely believe we all -- all of us developers -- can learn something about good UI design from bashtop. diff --git a/docs/colorschemes.md b/docs/colorschemes.md new file mode 100644 index 0000000..430a372 --- /dev/null +++ b/docs/colorschemes.md @@ -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 +``` + diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..f452106 --- /dev/null +++ b/docs/configuration.md @@ -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 +``` + diff --git a/docs/devices.md b/docs/devices.md new file mode 100644 index 0000000..4f9e34c --- /dev/null +++ b/docs/devices.md @@ -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. + diff --git a/docs/layouts.md b/docs/layouts.md new file mode 100644 index 0000000..c2f4a8b --- /dev/null +++ b/docs/layouts.md @@ -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 +``` + diff --git a/docs/releasing.md b/docs/releasing.md index e87e4de..8ad4498 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -1,23 +1,29 @@ -Current steps for a release: +# Current steps for a release -### gotop 1. Update Version in main.go 2. Update CHANGELOG.md 3. Tag 4. Push everything -5. When the github workflows complete, finish the draft release and publish. -6. Wait for the [Homebrew](https://github.com/xxxserxxx/homebrew-gotop) and [AUR](https://github.com/xxxserxxx/gotop-linux] projects to finish building. - 1. check out gotop-linux and run `aurpublish aur` and `aurpublish aur-bin` - 2. update the hashes in the Nix package (see below), test build, push a pull request - 3. notify Homebrew - -Homebrew is automatically updated. The AUR project still needs secret -credentials to aurpublish to the AUR repository, so the final publish step is -still currently manual. +5. Wait for the github workflows to complete +6. Download and verify the correct version of one of the binaries +7. Finish the draft release and publish. +8. Check gotop-builder for a successful everything build; if successful, publish. +10. Wait for the [AUR](https://github.com/xxxserxxx/gotop-linux] project to finish building. + 1. update arch (gotop-linux) and run `aurpublish gotop` and `aurpublish gotop-bin` + 2. Test install `gotop` and `gotop-bin` with running & version check +11. Notify Nix +12. ~~Notify Homebrew~~ Automated now. + +The AUR project still needs secret credentials to aurpublish to the AUR +repository, so the final publish step is still currently manual. Oh, what a tangled web. +## Nix + +I haven't yet figured this out, so currently just file a ticket and hope somebody on that end updates the package. + Nix adds new and interesting complexities to the release. 0. Download the gotop src package; run sha256 on it to get the hash @@ -27,11 +33,4 @@ Nix adds new and interesting complexities to the release. 3. `cd /mnt` 8. install & run vgo2nix to update deps.nix 7. `nix-build -A gotop` -8. When it fails, copy the hash and update the - - -For plugin development: -``` -V=$(git show -s --format=%cI HEAD | cut -b -19 | tr -cd '[:digit:]')-$(git rev-parse HEAD | cut -b -12) -go build -ldflags "-X main.Version=$V" -o gotop ./cmd/gotop -``` +8. When it fails, ... |