Skip to content

Commit d08ad6e

Browse files
committed
docs: move README & asset to docs dir; update demo img
Signed-off-by: NotAShelf <raf@notashelf.dev> Change-Id: I47770f97a8ddc10f66d22acf2f2d26836a6a6964
1 parent 014c1a3 commit d08ad6e

File tree

3 files changed

+43
-19
lines changed

3 files changed

+43
-19
lines changed

.github/assets/demo.png

-20.5 KB
Binary file not shown.

README.md renamed to docs/README.md

Lines changed: 43 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
<p>Microscopic fetch tool in Rust, for NixOS systems, with special emphasis on speed</p>
1111
<br/>
1212
<a href="#synopsis">Synopsis</a><br/>
13-
<a href="#features">Features</a> | <a href="#motivation">Motivation</a><br/> | <a href="#benchmarks">Benchmarks</a><br/>
13+
<a href="#features">Features</a> | <a href="#motivation">Motivation</a> | <a href="#benchmarks">Benchmarks</a><br/>
1414
<a href="#installation">Installation</a>
1515
<br/>
1616
</div>
@@ -27,11 +27,13 @@ communities. Aims to replace [fastfetch] on my personal system, but
2727
on your system: it is pretty _[fast](#benchmarks)_...
2828

2929
<p align="center">
30+
<br/>
3031
<img
3132
alt="latest demo"
32-
src="./.github/assets/demo.png"
33-
width="850px"
33+
src="./assets/demo.png"
34+
width="800px"
3435
>
36+
<br/>
3537
</p>
3638
3739
## Features
@@ -55,10 +57,14 @@ on your system: it is pretty _[fast](#benchmarks)_...
5557
- Shell Colors
5658
- Did I mention fast?
5759
- Respects [`NO_COLOR` spec](https://no-color.org/)
60+
- Funny [^2]
5861

5962
[^1]: With the Mold linker, which is enabled by default in the Flake package,
6063
the binary size is roughly 350kb. That's nearly 20kb reduction in size :)
6164

65+
[^2]: I don't know how else to describe the (unhealthy) amount of handwritten
66+
assembly that was written in order to make Microfetch faster.
67+
6268
## Motivation
6369

6470
[Rube-Goldmark Machine]: https://en.wikipedia.org/wiki/Rube_Goldberg_machine
@@ -87,14 +93,15 @@ solve a technical problem. The "problem" Microfetch solves is entirely
8793
self-imposed. On the matter of _size_, the project is written in Rust, which
8894
comes at the cost of "bloated" dependency trees and the increased build times,
8995
but we make an extended effort to keep the dependencies minimal and build times
90-
managable. The latter is also very easily mitigated with Nix's binary cache
96+
manageable. The latter is also very easily mitigated with Nix's binary cache
9197
systems. Since Microfetch is already in Nixpkgs, you are recommended to use it
9298
to utilize the binary cache properly. The usage of Rust _is_ nice, however,
9399
since it provides us with incredible tooling and a very powerful language that
94100
allows for Microfetch to be as fast as possible. ~~Sure C could've been used
95101
here as well, but do you think I hate myself?~~ Microfetch now features
96102
handwritten assembly to unsafely optimize some areas. In hindsight you all
97-
should have seen this coming. Is it faster? Yes.
103+
should have seen this coming. Is it faster? Yes. Should you use this? If you
104+
want to.
98105

99106
Also see: [Rube-Goldmark Machine]
100107

@@ -128,9 +135,19 @@ up to date, but I will try to update the numbers as I make Microfetch faster.
128135

129136
The point stands that Microfetch is significantly faster than every other fetch
130137
tool I have tried. This is to be expected, of course, since Microfetch is
131-
designed _explicitly_ for speed and makes some tradeoffs to achieve it's
138+
designed _explicitly_ for speed and makes some tradeoffs to achieve its
132139
signature speed.
133140

141+
> [!IMPORTANT]
142+
> Some tools are excluded. Yes, I know. If you think they are important and thus
143+
> should be covered in the benchmarks, feel free to create an issue. The purpose
144+
> of this benchmarks section is not to badmouth other projects, but to
145+
> demonstrate how much faster Microfetch is in comparison. Obviously Microfetch
146+
> is designed to be small (in the sense of scope) and fast (in every definition
147+
> of the word) so I speak of Microfetch's speed as a fact rather than an
148+
> advantage. Reddit has a surprising ability to twist words and misunderstand
149+
> ideals.
150+
134151
### Benchmarking Individual Functions
135152

136153
[Criterion.rs]: https://github.com/bheisler/criterion.rs
@@ -169,21 +186,27 @@ performance regressions.
169186
## Installation
170187

171188
> [!NOTE]
172-
> You will need a Nerdfonts patched font installed, and for your terminal
173-
> emulator to support said font. Microfetch uses nerdfonts glyphs by default,
189+
> You will need a Nerd Fonts patched font installed, and for your terminal
190+
> emulator to support said font. Microfetch uses Nerd Fonts glyphs by default,
174191
> but this can be changed by [patching the program](#customizing).
175192
176193
Microfetch is packaged in [nixpkgs](https://github.com/nixos/nixpkgs). It can be
177194
installed by adding `pkgs.microfetch` to your `environment.systemPackages`.
178-
Additionally, you can try out Microfetch in a Nix shell.
195+
Additionally, you can try out Microfetch in a Nix shell or install it using
196+
flakes on non-NixOS systems.
179197

180198
```bash
199+
# Enter a Nix shell with Microfetch; this will be lost on the next GC
181200
nix shell nixpkgs#microfetch
201+
202+
# Install Microfetch globally; this will be kept on GC
203+
nix profile add nixpkgs#microfetch
182204
```
183205

184206
Or run it directly with `nix run`
185207

186208
```bash
209+
# Run Microfetch from Nixpkgs. Subsequent runs will be faster.
187210
nix run nixpkgs#microfetch
188211
```
189212

@@ -200,15 +223,16 @@ have to be?
200223

201224
## Customizing
202225

203-
You can't.
226+
You can't*.
204227

205228
### Why?
206229

207-
Customization, of most kinds, are expensive: I could try reading environment
230+
Customization, of most kinds, is "expensive": I could try reading environment
208231
variables, parse command-line arguments or read a configuration file to allow
209232
configuring various fields but those inflate execution time and the resource
210233
consumption by a lot. Since Microfetch is closer to a code golf challenge than a
211-
program that attempts to fill a gap, I have elected not to make this trade.
234+
program that attempts to fill a gap, I have elected not to make this trade. This
235+
is, of course, not without a solution.
212236

213237
### Really?
214238

@@ -217,13 +241,13 @@ program that attempts to fill a gap, I have elected not to make this trade.
217241

218242
To be fair, you _can_ customize Microfetch by, well, patching it. It is
219243
certainly not the easiest way of doing so but if you are planning to change
220-
something in Microfetch, patching is the best way to go. It will also the only
221-
way that does not compromise on speed, unless you patch in bad code. Various
222-
users have adapted Microfetch to their distribution by patching the
223-
[main module] and inserting the logo of their choice. This is also the best way
224-
to go if you plan to make small changes. If your changes are not small, you
225-
might want to look for a program that is designed to be customizable; Microfetch
226-
is built for maximum performance.
244+
something in Microfetch, patching is the best way to go. It will also be the
245+
only way that does not compromise on speed, unless you patch in bad code.
246+
Various users have adapted Microfetch to their distribution of choice by
247+
patching the [main module] and inserting the logo of their choice. This is also
248+
the best way to go if you plan to make small changes. If your changes are not
249+
small, you might want to look for a program that is designed to be customizable;
250+
Microfetch is built for maximum performance and little else.
227251

228252
The Nix package allows passing patches in a streamlined manner by passing
229253
`.overrideAttrs` to the derivation. You can apply your patches in `patches` and

docs/assets/demo.png

35.3 KB
Loading

0 commit comments

Comments
 (0)