Forem: Yevhenii Babichenko

WezTerm: an actually good config key binding recipe

Yevhenii Babichenko — Mon, 03 Jun 2024 16:54:01 +0000

While WezTerm is a great terminal with sane defaults, it doesn't provide
the default key binding to open the configuration file and edit it. That is
understandable, everyone may have their own preference for that. Here we will
figure out the recipe that would work everywhere and abide by modern standards.

The original article was posted at my homepage: https://eugene-babichenko.github.io/blog/2024/06/03/wezterm-open-config/

In my opinion, the proper way to go is to open the configuration file with the
editor specified in the EDITOR environment variable. I am also using macOS
most of the time, so the most natural key binding to configure something is
Cmd+,. In many applications this key binding is universal for all operating
systems.

It is easy to find out where the WezTerm configuration file is located: there is
always the WEZTERM_CONFIG_FILE variable. Also there is always the
WEZTERM_CONFIG_DIR variable that should allow us to specify the working
directory for our editor.

The problem with the EDITOR variable is that it may not be immediately
accessible to WezTerm config via os.getenv("EDITOR") if it was specified in
your shell configuration (e.g. .bashrc) and not it some other magical place.
To solve this we will obviously need to load our editor inside the shell, which
is conveniently accessible via the SHELL variable.

Considering all of the above, we end up with the code like this:

local wezterm = require("wezterm")
local config = wezterm.config_builder()
config.keys = {
  {
    key = ",",
    mods = "SUPER",
    action = act.SpawnCommandInNewWindow({
      cwd = os.getenv("WEZTERM_CONFIG_DIR"),
      args = { os.getenv("SHELL"), "-c", "$EDITOR $WEZTERM_CONFIG_FILE" },
    }),
  },
}

This greatness of this specific recipe is that it will work regardless of your
preferred shell end editor as long as the EDITOR variable is set. The -c
flag is accepted by all major *nix shells. Also, regardless of the fact your
editor is running with an shell, the window will close immediately after you
close the editor. And of course, you can swap SpawnCommandInNewWindow with
SpawnCommandInNewTab or any custom SpawnCommand call.

Automated multi-platform releases with GitHub Actions

Yevhenii Babichenko — Sat, 09 May 2020 14:15:21 +0000

The original article published in my blog.

GitHub Actions allows you to create releases, build binaries, and upload them. Unfortunately, there is no official tutorial on how to create a release, build the code for multiple platforms, and upload binaries to the release. I will cover how to do that without any 3rd-party actions in this post. I assume that you are familiar with the basics of GitHub Actions.

Selecting the workflow trigger

First things first: let's select the trigger for our workflow. I git tags for versioning, and for simplicity they begin with v, so the simplest trigger we can use

on:
  push:
    tags:
      - 'v[0-9]+.*'

Let's continue to defining our jobs.

Creating the release

Since we are going to do multiple builds defined in a matrix, creating the new release should be obviously done in a separate job. GitHub has the official example for that. The only difference from the example is that we add the job output. This output will be used by build jobs to upload their results to the created release.

jobs:
  create_release:
    name: Create release
    runs-on: ubuntu-latest
    # Note this. We are going to use that in further jobs.
    outputs:
      upload_url: ${{ steps.create_release.outputs.upload_url }}
    steps:
      - name: Create release
        id: create_release
        uses: actions/create-release@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          draft: false
          prerelease: false

Build and upload

This is the final step. I won't dive into the details too much because you will have your own build scenarios. But here are a couple of things to highlight:

The build jobs will have create_release as a dependency.
The output of create_release is used in the last "upload step".

You can get more details on assets uploads here.

# ...
  release_assets:
    name: Release assets
    needs: create_release # we need to know the upload URL
    runs-on: ${{ matrix.config.os }} # we run many different builds
    strategy:
      # just an example matrix
      matrix:
        config:
          - os: ubuntu-latest
          - os: macos-latest
          - os: windows-latest
    steps:
      # checkout of cource
      - name: Checkout code
        uses: actions/checkout@v1
      # ... whatever build and packaging steps you need here
      # and finally do an upload!
      - name: Upload release assets
        uses: actions/upload-release-asset@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          upload_url: ${{ needs.create_release.outputs.upload_url }}
          # This is how it will be named on the release page. Put hatever name
          # you like, remember that they need to be different for each platform.
          # You can choose any build matrix parameters. For Rust I use the
          # target triple.
          asset_name: program-name-${{ matrix.config.os }}
          # The path to the file you want to upload.
          asset_path: ./path/to/your/file
          # probably you will need to change it, but most likely you are
          # uploading a binary file
          asset_content_type: application/octet-stream

A note on executable formats: if you are building for Windows and uploading an .exe you can use two different steps for uploading the executable. One should have if: matrix.config.os == 'windows-latest' and asset path asset_path: ./path/to/your/file.exe. For *nix operating systems that usually are not using extensions for executables, use if: matrix.config.os != 'windows-latest'. This is a very useful trick overall when creating jobs that should handle multiple platforms.

How to force Rust compiler to use several x86 instructions (popcount, etc)

Yevhenii Babichenko — Wed, 13 Nov 2019 19:28:51 +0000

Sometimes you need tricky operations on your binary data like counting bits, leading or trailing zeros and so on (for example, when you want to implement HAMT or sparse arrays). In Rust this is achieved by using methods like .count_ones() and .trailing_zeros(). The problem with those methods is that they are usually expanded in a huge pile of assembler code. But x86 (and some other architectures) have instructions to perform these counts (specifically, popcnt and tzcnt) and they are really fast (1 cycle for execution and latency of 3 cycles). Today we will learn how to force Rust compiler to use those instructions and what are the possible pitfalls.

Originally published on my website.

Let's start with an example. Here's the code that finds population counts of random integers (on Rust Playground):

use rand::prelude::*;

// this is only to have this function separately in the asm output
#[inline(never)]
fn count(a: u32) -> u32 {
    a.count_ones()
}

fn main() {
    let a: u32 = random();
    println!("{}", count(a));
    println!("{}", count(a + 1));
}

And the count function looks like that:

playground::count:
    mov eax, edi
    shr eax
    and eax, 1431655765
    sub edi, eax
    mov eax, edi
    and eax, 858993459
    shr edi, 2
    and edi, 858993459
    add edi, eax
    mov eax, edi
    shr eax, 4
    add eax, edi
    and eax, 252645135
    imul    eax, eax, 16843009
    shr eax, 24
    ret

Wow. A huge pile of instructions and magic numbers. This is clearly not something we would like to see, especially in performance-critical places. Let's make this a little bit better (on Rust Playground):

use rand::prelude::*;

// this is only to have this function separately in the asm output
#[inline(never)]
#[cfg_attr(target_arch = "x86_64", target_feature(enable = "popcnt"))]
unsafe fn count(a: u32) -> u32 {
    a.count_ones()
}

fn main() {
    let a: u32 = random();
    println!("{}", unsafe { count(a) });
    println!("{}", unsafe { count(a + 1) });
}

And here is the assembly code of count:

playground::count:
    popcnt  eax, edi
    ret

Only a single very fast instruction! And that this will work with all integer types. There is a pitfall though: Rust requires us to mark functions as unsafe when we use target_feature so it makes sense to make functions using those features as small as possible.

Also, you can do something similar with .trailing_zeros() or .leading_zeros() by using target_feature(enable = "bmi1").

To find feature names you can refer to architecture-specific intrinsics
documentation.

That's all, hope you find it useful!

Generating pretty version strings (including nightly) with Git and Makefiles

Yevhenii Babichenko — Sat, 28 Sep 2019 13:55:40 +0000

In my recent project, I faced the need to generate pretty version numbers for my
local and nightly builds. Here I will describe the approach I came up with. In
this tutorial, we will use Git, which stores version tags and the entire setup
uses Makefiles. However, you should be able to adapt this approach to any build
system.

In the end, we will be able to get pretty and very informative version strings
like 0.2.1-next-314da12-20190928.

You can check out the code from this article in this Gist.

First of all, we need to have versions based on git tags. Here, I will assume
that version tags are in the format v0.1.2. Given that, we can extract the
latest tag and strip the v:

TAG_COMMIT := $(shell git rev-list --abbrev-commit --tags --max-count=1)
# `2>/dev/null` suppress errors and `|| true` suppress the error codes.
TAG := $(shell git describe --abbrev=0 --tags ${TAG_COMMIT} 2>/dev/null || true)
# here we strip the version prefix
VERSION := $(TAG:v%=%)

This script will not fail if there are no tags in the current repository, but
this will generate an empty version string. In this case, we can build a version
string from the latest git commit hash and add the commit date for additional
info:

# get the latest commit hash in the short form
COMMIT := $(shell git rev-parse --short HEAD)
# get the latest commit date in the form of YYYYmmdd
DATE := $(shell git log -1 --format=%cd --date=format:"%Y%m%d")
# check if the version string is empty
ifeq $(VERSION,)
    VERSION := $(COMMIT)-$(DATA)
endif

This will give us a version string in a format like 314da12-20190928 which
gives us pretty much information about the build. Particularly, when the change
was made and which commit we should look for.

On top of that, we can deal with nightly builds that appeared after a particular
version like that: 0.2.1-next-314da12-20190928. This line contains even more
information as it includes the last stable version. We can quickly grab the
version number and compare our changes to it to see what went wrong. This is how
we generate this:

ifneq ($(COMMIT), $(TAG_COMMIT))
    VERSION := $(VERSION)-next-$(COMMIT)-$(DATE)
endif

Finally, we can indicate that we were building from a dirty git state (e.g. we
had uncommitted changes during the build):

# git status --porcelain outputs a machine-readable text and the output is empty
# if the working tree is clean
ifneq ($(shell git status --porcelain),)
    VERSION := $(VERSION)-dirty
endif

This is how the script looks in the end:

TAG_COMMIT := $(shell git rev-list --abbrev-commit --tags --max-count=1)
TAG := $(shell git describe --abbrev=0 --tags ${TAG_COMMIT} 2>/dev/null || true)
COMMIT := $(shell git rev-parse --short HEAD)
DATE := $(shell git log -1 --format=%cd --date=format:"%Y%m%d")
VERSION := $(TAG:v%=%)
ifneq ($(COMMIT), $(TAG_COMMIT))
    VERSION := $(VERSION)-next-$(COMMIT)-$(DATE)
endif
ifeq $(VERSION,)
    VERSION := $(COMMIT)-$(DATA)
endif
ifneq ($(shell git status --porcelain),)
    VERSION := $(VERSION)-dirty
endif

That's all! For me, this looks very good, because it does not use any additional
tools apart from Git and make. Hope you will find this useful!

As a bonus, I would like to show how I integrate that with Go builds.

First, you need to specify the version variable in your main package (I do
it exactly this way because this is compatible with GoReleaser):

package main

import (
    // ...
)

var version = "dev"

func main() {
    // ...
}

And this is my Makefile for filling in that variable

FLAGS := -ldflags "-X main.version=$(VERSION)"

build:
    go build $(FLAGS) -o projectname-$(VERSION) main.go

run:
    go run $(FLAGS) main.go

install:
    go install $(FLAGS)

The original article is placed at my github.io site