Brendan A R Sechter’s Development Blog | Jekyll

WASM on a Jekyll Blog with Rust and wasm-bindgen

2026-01-26T04:19:39+00:00

Jekyll generates static pages from templates. It is often used for blogs, like this one. Sometimes you want to include interactive elements, like calculators.

This post documents how web assembly (WASM) driven UI widget can be included in a Jekyll blog post with Rust and wasm-bindgen. It is a tutorial on getting the WASM to work, not a deep dive into wasm-bindgen.

The post largely documents the steps taken to get the following UI-widget up and running on this page.

Software Versions

# Date (UTC)
$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2026-01-26 04:19:39 +0000

# OS and Version
$ uname -vm
Darwin Kernel Version 23.6.0: Mon Jul 29 21:14:30 PDT 2024; root:xnu-10063.141.2~1/RELEASE_ARM64_T6000 arm64

$ sw_vers
ProductName:		macOS
ProductVersion:		14.6.1
BuildVersion:		23G93

# Hardware Information
$ system_profiler SPHardwareDataType | sed -n '8,10p'
      Chip: Apple M1 Max
      Total Number of Cores: 10 (8 performance and 2 efficiency)
      Memory: 32 GB

# Shell and Version
$ echo "${SHELL}"
/bin/bash

$ "${SHELL}" --version  | head -n 1
GNU bash, version 3.2.57(1)-release (arm64-apple-darwin23)

# Rust Installation Versions
$ cargo --version
cargo 1.93.0 (083ac5135 2025-12-15)

Instructions

First, create a new library project.

PROJECT_NAME="post_webasm_on_jekyll"
cargo new --lib "${PROJECT_NAME}"
cd "${PROJECT_NAME}"

Next, add the js-sys, wasm-bindgen, and web-sys dependencies for this project.

cargo add js-sys
cargo add wasm-bindgen
cargo add web-sys \
  -F Document -F Element -F Event -F EventTarget \
  -F HtmlElement -F HtmlInputElement -F Node -F Window

WASM needs to be packaged as a dynamic library, so set the library type to a C dynamic library using your editor of choice.

Cargo.toml partial listing

[lib]
crate-type = ["cdylib"]

Your complete Cargo.toml should look something like this.

Cargo.toml full listing

[package]
name = "post_webasm_on_jekyll"
version = "0.1.0"
edition = "2024"

[lib]
crate-type = ["cdylib"]

[dependencies]
js-sys = "0.3.85"
wasm-bindgen = "0.2.108"
web-sys = { version = "0.3.85", features = ["Document", "Element", "Event", "EventTarget", "HtmlElement", "HtmlInputElement", "Node", "Window", ] }

Replace src/lib.rs with the following contents.

src/lib.rs full listing

use wasm_bindgen::prelude::*;
use wasm_bindgen::JsCast;
use web_sys::{HtmlElement, HtmlInputElement, Event};

#[wasm_bindgen]
pub fn inject_ui(anchor_id: &str) {
    let document = web_sys::window()
        .unwrap()
        .document()
        .unwrap();

    let anchor = document
        .get_element_by_id(anchor_id)
        .expect("anchor element not found");

    let parent = anchor
        .parent_node()
        .expect("anchor has no parent");

    let container = document
        .create_element("div")
        .unwrap();
    container.set_class_name("wasm-greeting-ui");

    // --- Line 1: label + input ---
    let line1 = document.create_element("div").unwrap();
    line1.set_class_name("line1");

    let label = document.create_element("label").unwrap();
    label.set_text_content(Some("Name: "));
    label.set_attribute("for", "name-input").unwrap();

    let input: HtmlInputElement = document
        .create_element("input")
        .unwrap()
        .dyn_into()
        .unwrap();
    input.set_type("text");
    input.set_id("name-input");
    input.set_placeholder("Enter your name");

    // append label + input to line1 container
    line1.append_child(&label).unwrap();
    line1.append_child(&input).unwrap();

    // --- Line 2: message ---
    let message: HtmlElement = document
        .create_element("div")
        .unwrap()
        .dyn_into()
        .unwrap();
    message.set_class_name("line2");

    update_message(&message, None);

    // Append line1 and line2 to the main container
    container.append_child(&line1).unwrap();
    container.append_child(&message).unwrap();

    // Replace the anchor with the new UI
    parent.replace_child(&container, &anchor).unwrap();

    // --- Event listener ---
    let message_clone = message.clone();
    let input_clone = input.clone();
    let closure = Closure::wrap(Box::new(move |_event: Event| {
        let value = input_clone.value();
        if value.trim().is_empty() {
            update_message(&message_clone, None);
        } else {
            update_message(&message_clone, Some(&value));
        }
    }) as Box<dyn FnMut(Event)>);

    input
        .add_event_listener_with_callback("input", closure.as_ref().unchecked_ref())
        .unwrap();

    closure.forget();
}

fn update_message(message: &HtmlElement, name: Option<&str>) {
    let name = name.unwrap_or("USERNAME");
    message.set_text_content(Some(&format!("Hello, {}!", name)));
}

Install wasm-pack with cargo if you need to.

cargo install wasm-pack

Build the WASM with the following command.

wasm-pack build --target web

wasm-pack produces files in pkg/, which Jekyll will not serve automatically.

tree pkg/

Expected Output

pkg/
├── post_webasm_on_jekyll.d.ts
├── post_webasm_on_jekyll.js
├── post_webasm_on_jekyll_bg.wasm
├── post_webasm_on_jekyll_bg.wasm.d.ts
└── package.json

1 directory, 5 files

To serve these files, they need to be copied into ${JEKYLL_PATH}/assets, ideally in something like the wasm/${PROJECT_NAME} subdirectory to keep things organized. Note that you probably do not want to copy the generated .gitignore. Using pkg/* ensures we copy all build artifacts while ignoring the hidden .gitignore file that wasm-pack creates, which would otherwise hide your WASM files from git and complicate deployment. Use the following command to copy the files.

PROJECT_NAME="post_webasm_on_jekyll"
JEKYLL_PATH="/path/to/jekyll/blog"
mkdir -p "${JEKYLL_PATH}/assets/wasm/${PROJECT_NAME}"
cp -r pkg/* "${JEKYLL_PATH}/assets/wasm/${PROJECT_NAME}/"

If you want to overwrite existing files automatically, add -f.

cp -rf pkg/* "${JEKYLL_PATH}/assets/wasm/${PROJECT_NAME}/"

After copying, all files should be present in the assets directory.

ls -1 "${JEKYLL_PATH}/assets/wasm/${PROJECT_NAME}/"

Expected Output

package.json
post_webasm_on_jekyll.d.ts
post_webasm_on_jekyll.js
post_webasm_on_jekyll_bg.wasm
post_webasm_on_jekyll_bg.wasm.d.ts

Inline an HTML script tag in the blog post to load the WASM. Note that the id of the script tag is used as an anchor, which the Rust code will replace with the WASM-driven UI. Alternatively, you can use an empty div (

) or a self-closing tag like as your anchor if you prefer to keep the script logic and the UI placement separate.

Also, you can add CSS in a style block above the script tag, or put it in an included external file if you want to style your UI.

<style>
  .wasm-greeting-ui {
    max-width: 300px;
    font-family: sans-serif;
    border: 2px solid red;   /* red outline */
    padding: 0.75rem;        /* some space inside the box */
    border-radius: 4px;      /* optional: slightly rounded corners */
    background-color: #fff;  /* optional: white background */
  }

  .wasm-greeting-ui .line1 {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    margin-bottom: 0.5rem;
  }

  .wasm-greeting-ui .line2 {
    font-weight: bold;
  }
style>

Future Reading

If you want to explore more about WebAssembly, Rust, and integrating dynamic UIs in static sites, these resources are highly recommended:

Rust and WASM Fundamentals: Learn how Rust compiles to WebAssembly, how to use wasm-bindgen, and best practices for building interactive web apps. See the official Rust and WebAssembly Book.
Jekyll Assets & Static Sites: Tips on structuring static assets in Jekyll, managing JavaScript/CSS, and optimizing for WASM loading can be found in the Jekyll Assets Documentation.

References:

Adding Images and Downloads to a GitHub Pages Jekyll Blog

2016-08-30T19:45:55+00:00

This post covers adding images to a GitHub Pages Jekyll blog. This solution also works for downloads, like PDFs.

Software Versions

$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2016-08-30 19:45:55 +0000
$ uname -vm
FreeBSD 12.0-CURRENT #0 r304324: Thu Aug 18 13:27:23 JST 2016     root@mirage.sennue.com:/usr/obj/usr/src/sys/MIRAGE_KERNEL  amd64
$ ruby --version
ruby 2.2.5p319 (2016-04-26 revision 54774) [amd64-freebsd11]
$ jekyll --version
jekyll 3.0.1

Instructions

First, create an assets directory.

mkdir assets

Add an image to the assets directory.

cp path/to/image.png ./assets/

The image can be displayed as follows.

![useful image]({{ site.url }}/assets/image/post_adding_images_and_downloads_to_a_github_pages_jekyll_blog/image.png)

Note that downloads can be made available with the same strategy.

You can download the PDF [here]({{ site.url }}/assets/pdf/post_adding_images_and_downloads_to_a_github_pages_jekyll_blog/document.pdf).

You can download the PDF here.

References:

Adding MathJax to a GitHub Pages Jekyll Blog

2016-08-21T23:41:54+00:00

This post covers adding MathJax support to a GitHub Pages Jekyll blog.

Software Versions

$ date -u "+%Y-%m-%d %H:%M:%S +0000"
2016-08-21 23:41:54 +0000
$ uname -vm
FreeBSD 11.0-ALPHA6 #0 r302384: Thu Jul  7 22:40:47 JST 2016     root@mirage.sennue.com:/usr/obj/usr/src/sys/MIRAGE_KERNEL  amd64
$ ruby --version
ruby 2.2.5p319 (2016-04-26 revision 54774) [amd64-freebsd11]
$ jekyll --version
jekyll 3.0.1

Instructions

Add the following code to _includes/mathjax.html.

_includes/mathjax.html.

{% if page.mathjax %}



{% endif %}

Add the following line to the header in _layouts/post.html or anywhere else you want to use MathJax.

_layouts/post.html partial listing

{% include mathjax.html %}

Add the following line to the YAML front matter of a post to enable MathJax on a post by post basis.

mathjax: true

For example, the front matter of this post looks like this. Note that Disqus comments have been added with the same strategy.

---
layout: post
mathjax: true
comments: true
title:  "Adding MathJax to a GitHub Pages Jekyll Blog"
date:   2016-08-21 23:41:54 +0000
categories: github jekyll
---

If all goes well, you should be able to use MathJax inline and display modes. Note that the MathJax dynamic preview can be useful when formatting complex equations.

In N-dimensional simplex noise, the squared kernel summation radius $r^2$ is $\frac 1 2$
for all values of N. This is because the edge length of the N-simplex $s = \sqrt {\frac {N} {N + 1}}$
divides out of the N-simplex height $h = s \sqrt {\frac {N + 1} {2N}}$.
The kerel summation radius $r$ is equal to the N-simplex height $h$.

$$ r = h = \sqrt{\frac {1} {2}} = \sqrt{\frac {N} {N+1}} \sqrt{\frac {N+1} {2N}} $$

In N-dimensional simplex noise, the squared kernel summation radius $r^2$ is $\frac 1 2$ for all values of N. This is because the edge length of the N-simplex $s = \sqrt {\frac {N} {N + 1}}$ divides out of the N-simplex height $h = s \sqrt {\frac {N + 1} {2N}}$. The kerel summation radius $r$ is equal to the N-simplex height $h$.

\[r = h = \sqrt{\frac {1} {2}} = \sqrt{\frac {N} {N+1}} \sqrt{\frac {N+1} {2N}}\]

References:

Adding Disqus to a Jekyll Blog

2016-02-14T20:56:57+00:00

A Jekyll blog is not backed by a database. Out of the box, there is no way for people to comment on or discuss blog posts. Disqus is a third party service that can be used to get around that limitation. This post covers adding Disqus to a Jekyll blog.

Software Versions

$ date
February 15, 2016 at 05:56:57 PM JST
$ uname -vm
FreeBSD 11.0-CURRENT #0 r287598: Thu Sep 10 14:45:48 JST 2015     root@:/usr/obj/usr/src/sys/MIRAGE_KERNEL  amd64
$ ruby --version
ruby 2.1.8p440 (2015-12-16 revision 53160) [amd64-freebsd11]
$ jekyll --version
jekyll 3.0.1

Instructions

First, install Jekyll and register your site with Disqus.

Add the following code to _includes/disqus.html. Remember to change the this.page.url line to the URL of your blog. The s.src line will need to point to your Disqus short name URL. Consider copying the Universal Embed Code directly from Disqus instead of this post.

{% if page.comments %}
 id="disqus_thread">


{% endif %}

Add the following line to the end of _layouts/post.html or anywhere else you want to display comments.

{% include disqus.html %}

Add the following line to the YAML front matter of a post to enable comments on a post by post basis.

comments: true

For example, the front matter of this post looks like this.

---
layout: post
comments: true
title:  "Adding Disqus to a Jekyll Blog"
date:   2016-02-15 05:56:57 +0900
categories: jekyll disqus
---

Optionally, to facilitate displaying comment counts add the following to _layouts/default.html before the closing body tag. Change SHORTNAME to the Disqus shortname you are using.

Add #disqus_thread to the end of a URL and Disqus will count the comments on the page the link points to. For example, my _layouts/post.html contains the following code. Note the comment count at the top of this post.

{% if page.comments %} •  href="https://sgeos.github.io{{ page.url }}#disqus_thread">0 Comments{% endif %}

index.html contains the following code to display the comment count for each post in the list.

 href="https://sgeos.github.io{{ post.url }}#disqus_thread">0 Comments

Note that moving a post from _drafts/ to _posts/ may change the URL of the post. This will cause any comments added to the draft to disappear. The Disqus Migration Tools can be used move comments to the new URL.

References:

UNIX ARM Assembler on Android

2016-01-07T22:12:57+00:00

Months ago, someone on the FreeBSD forums wanted help getting an assebly language program running on a 64 bit intel machine. I read through the FreeBSD Developers’ Handbook x86 Assembly Language Programming section, and sure enough the 32 bit examples did not work. x86 and x86-64 assembler are just plain different. Also, the ABI is completely different.

I managed to find an x86-64 hello world example for FreeBSD. The environment works. Great! Now what? The problem with hello world examples is that there is no input. Without knowing where to go next, a hello world example is not very useful. Between the Developer’s Handbook, the System V AMD64 ABI Reference and an x86-64 tutorial (that has since disappeared) I managed to write a command line utility in x86-64 ASM that processes command line arguments.

Then I thought back to the days when I wrote ARM assembler for the Gameboy Advance and Nintendo DS and wanted to write a command line UNIX utility in ARM assembler. My Raspberry Pi was halfway around the world at the time, but my Android phone was handy. No FreeBSD on my phone, but a few people had written hello world examples for android (1) (2) (3). FreeBSD and Linux appear to use the same ARM EABI documented on the ARM site. Also, Android’s bionic C libaray has a lot of BSD in it.

The Developer’s Handbook notes that “Assembly language programming under UNIX® is highly undocumented”. I am writing this post to document writing a command line UNIX application in assembler that conforms to the ARM EABI. Specifically, this application will run on Android. Remember, there has never been an easier time to learn assembler!

My GitHub repository for this project can be found here. Please note that manually linking object files is probably not standard Android NDK usage. The build instructions may break in the future. If that happens, good luck figuring the necessary flags to build the examples. =)

Software Versions

$ date
January  8, 2016 at 11:32:13 AM JST
$ uname -a
Darwin siderite.local 15.2.0 Darwin Kernel Version 15.2.0: Fri Nov 13 19:56:56 PST 2015; root:xnu-3248.20.55~2/RELEASE_X86_64 x86_64
$ adb version
Android Debug Bridge version 1.0.32
$ $ANDROID_NDK_STANDALONE_TOOLCHAIN/bin/clang --version
clang version 3.6 
Target: armv5te-none-linux-androideabi
Thread model: posix
$ $ANDROID_NDK_STANDALONE_TOOLCHAIN/bin/arm-linux-androideabi-as --version
GNU assembler (GNU Binutils) 2.24.90
This assembler was configured for a target of `arm-linux-androideabi'.
$ $ANDROID_NDK_STANDALONE_TOOLCHAIN/bin/arm-linux-androideabi-ld --version
GNU gold (GNU Binutils 2.24.90) 1.11
$ $ANDROID_NDK_STANDALONE_TOOLCHAIN/bin/arm-linux-androideabi-gdb --version
GNU gdb (GDB) 7.7
This GDB was configured as "--host=x86_64-apple-darwin --target=arm-linux-android".
$ adb shell "uname -a" # Nexus 5; Cyanogenmod CM-13.0-20160108-NIGHTLY; Android 6.0.1
Linux localhost 3.4.0-cyanogenmod-g9e39333 #1 SMP PREEMPT Wed Jan 6 19:02:34 PST 2016 armv7l
$ adb shell "toybox --version" # for chmod; busybox will work
ac4365b3c292-android

Instructions

First, install the Android SDK and Android NDK. Make sure ADB has been installed and you connect to your test device.

$ adb devices
List of devices attached 
071f7b2ef0e95581	device

$ adb shell "uname"
Linux

A rooted device is required to run ASM programs on Android with these instructions. Running ADB as root is handy. You will need chmod, so you will need to install busybox or some other box that provides the same functionality.

$ adb root
restarting adbd as root
$ adb shell "chmod +x /root/does_not_exist"
chmod: /root/does_not_exist: No such file or directory

Next, install the Android NDK standalone toolchain. The sysroot path probably needs to be defined. Also adding paths for the SDK, NDK and the to be generated standalone NDK is a good idea. I added these lines to my .profile. Adjust pathnames as necessary.

export ANDROID_SDK="$HOME/android-sdk"
export ANDROID_NDK="$HOME/android-ndk"
export ANDROID_NDK_STANDALONE_TOOLCHAIN="$HOME/android-ndk-standalone-toolchain"
export SYSROOT="$ANDROID_NDK_STANDALONE_TOOLCHAIN/sysroot"
export PATH="$ANDROID_SDK/tools:$ANDROID_SDK/platform-tools:$ANDROID_NDK_STANDALONE_TOOLCHAIN/bin:$PATH"

Next, reload .profile and generate the standalone toolchain. The Android NDK standalone toolchain page has instructions for targetting different architectures and Android versions.

. .profile
$ANDROID_NDK/build/tools/make-standalone-toolchain.sh \
  --toolchain=arm-linux-androideabi-clang3.6 \
  --install-dir=$ANDROID_NDK_STANDALONE_TOOLCHAIN

64 bit ARM devices use aarch64 instead of arm. The following commands may be useful when trying to figure out the architecture of your device.

adb shell "getprop ro.product.cpu.abi"
adb shell "getprop ro.product.cpu.abi2"

The first program to build and run is a hello world example written in C. In general, it is generally a good idea to have a working C implementation before writing anything in ASM.

// main.c
#include 

int main(int argc, char **argv)
{
	printf("Hello, World! [C]\n");
	return 0;
}

Build it with the following commands.

CRT="$SYSROOT/usr/lib/crtbegin_dynamic.o $SYSROOT/usr/lib/crtend_android.o"
$ANDROID_NDK_STANDALONE_TOOLCHAIN/bin/clang --sysroot=$SYSROOT -fPIE -DANDROID -g -c main.c -o main.o 
$ANDROID_NDK_STANDALONE_TOOLCHAIN/bin/arm-linux-androideabi-ld --sysroot=$SYSROOT -pie --dynamic-linker=/system/bin/linker main.o $CRT -o c-hello-world -lc

This is a funny way of building a C program. What is going on? The end goal is to build and run assembler programs. Assembly files need to run through the assebler and the linker. In order to link ASM object files with C object files all object files need to be manually linked. The entry point to a C program is main, but the program really takes control in the _start function. The CRT files contain this _start function. It has all of the setup code for the “C runtime”. This code zeros memory and does other boilerplate tasks. Your compiler usually includes the C runtime automatically so you do not need to think about it. The -lc flag links the standard C library. This is another step your compiler usually handles automatically.

Running the program on the phone should print “Hello, World! [C]”. This will remount the system partition of your phone in read write mode. If you do not know what that means stop reading and do not proceed.

adb root
adb remount
adb shell "mkdir /system/test"
adb push c-hello-world /system/test
adb shell "chmod +x /system/test/c-hello-world"
adb shell /system/test/c-hello-world

With the C version working, it is time to rewrite the program in ARM ASM. Let us start with a header that defines Android system calls.

@ system.inc
@ Android Syscall Reference https://code.google.com/p/android-source-browsing/source/browse/libc/SYSCALLS.TXT?repo=platform--bionic&r=cd15bacf334ab254a5f61c3bba100adde1b6b80a

.set stdin,  0
.set stdout, 1
.set stderr, 2

.set SYS_nosys, 0
.set SYS_exit,  1
.set SYS_fork,  2
.set SYS_read,  3
.set SYS_write, 4
.set SYS_open,  5
.set SYS_close, 6

.macro sys.syscall id
	mov	r7, \id
	swi	$0
.endm

.macro sys.exit
	sys.syscall $SYS_exit
.endm

.macro sys.fork
	sys.syscall $SYS_fork
.endm

.macro sys.read
	sys.syscall $SYS_read
.endm

.macro sys.write
	sys.syscall $SYS_write
.endm

.macro sys.open
	sys.syscall $SYS_open
.endm

.macro sys.close
	sys.syscall $SYS_close
.endm

Next, the main assembler file.

@ start.s
.include "system.inc"
	.syntax unified
	.set ALIGNMENT,8

.text
	.align ALIGNMENT
	.global _start
_start:
	nop @ for gbd breakpoint

	@ Hello World
	@ sys.write(stdout, message, length)
	mov	r0,$stdout
	adr	r1,message
	mov	r2,$length
	sys.write

	@ sys.exit(0)
	mov	r0,$0
	sys.exit

@ Data needs to be in .text for PIE
@.data
message:
	.asciz "Hello, World! [ASM]\n"
length = . - message
	.align ALIGNMENT

The next step is building the ASM version.

$ANDROID_NDK_STANDALONE_TOOLCHAIN/bin/arm-linux-androideabi-as --gdwarf2 start.s -o start.o
$ANDROID_NDK_STANDALONE_TOOLCHAIN/bin/arm-linux-androideabi-ld --sysroot=$SYSROOT -pie --dynamic-linker=/system/bin/linker start.o -o asm-hello-world

The start.s file contains a start function, so the C runtime is not necessary. Functions from the C library can be called from assebler, but this function is using system calls, so -lc is not necessary.

Running it on the phone should print “Hello, World! [ASM]”.

adb push asm-hello-world /system/test
adb shell "chmod +x /system/test/asm-hello-world"
adb shell /system/test/asm-hello-world

A Makefile for the hello world project looks like this.

TOOLCHAIN=$(ANDROID_NDK_STANDALONE_TOOLCHAIN)
SYSROOT=$(TOOLCHAIN)/sysroot
CC=$(TOOLCHAIN)/bin/clang --sysroot=$(SYSROOT)
AS=$(TOOLCHAIN)/bin/arm-linux-androideabi-as
LD=$(TOOLCHAIN)/bin/arm-linux-androideabi-ld --sysroot=$(SYSROOT)
CRT=$(SYSROOT)/usr/lib/crtbegin_dynamic.o $(SYSROOT)/usr/lib/crtend_android.o
INSTALL=/system/test

CFLAGS=-fPIE -DANDROID -g
ASFLAGS=--gdwarf2
LDFLAGS=-pie --dynamic-linker=/system/bin/linker

ASM_TARGET=asm-hello-world
ASM_PARAM=
ASM_DEPS=system.inc
ASM_OBJ=start.o
ASM_LIBS=

C_TARGET=c-hello-world
C_PARAM=
C_DEPS=
C_OBJ=main.o $(CRT)
C_LIBS=-lc

all: $(ASM_TARGET) $(C_TARGET)

force: clean all

$(C_TARGET): $(C_OBJ)
	$(LD) $(LDFLAGS) $^ -o $@ $(C_LIBS)

$(ASM_TARGET): $(ASM_OBJ)
	$(LD) $(LDFLAGS) $^ -o $@ $(ASM_LIBS)

%.o: %.c $(C_DEPS)
	$(CC) $(CFLAGS) -c $< -o $@

%.o: %.s $(ASM_DEPS)
	$(AS) $(ASFLAGS) $< -o $@

install: all
	adb root
	adb remount
	adb shell "mkdir $(INSTALL)"
	adb push $(ASM_TARGET) $(INSTALL)
	adb push $(C_TARGET) $(INSTALL)
	adb shell "chmod +x $(INSTALL)/$(ASM_TARGET) $(INSTALL)/$(C_TARGET)"

uninstall:
	adb root
	adb remount
	adb shell "mkdir $(INSTALL)"
	adb shell "rm -rf $(INSTALL)/$(ASM_TARGET) $(INSTALL)/$(C_TARGET)"
	adb shell "rmdir $(INSTALL)"

test:
	adb root
	adb shell "$(INSTALL)/$(ASM_TARGET) $(ASM_PARAM) && $(INSTALL)/$(C_TARGET) $(C_PARAM)"

clean:
	rm -rf $(ASM_TARGET) $(C_TARGET) *.o

The next program will echo all of the command line arguments. This is the C source code:

// main.c
#include 
#include 
#include 

// newer NDK removed SYS macros
#ifndef SYS_exit
  #define SYS_exit __NR_exit
#endif
#ifndef SYS_write
  #define SYS_write __NR_write
#endif

#define BUFFER_SIZE  2048
#define MESSAGE      "Args: [C]\n"

char buffer[BUFFER_SIZE];

const char message[] = MESSAGE;
const int  length    = sizeof MESSAGE - 1; // sizeof inclues \0

int main(int argc, char** argv)
{
  // write message
  syscall(SYS_write, STDOUT_FILENO, message, length);

  // loop over argv until argvn_ptr is null
  char *argvn_ptr = *(argv++);
  while (NULL != argvn_ptr) {
    char *buffer_ptr = buffer;
    // copy from argvn_ptr to buffer_ptr until \0 is encountered
    while ('\0' != *argvn_ptr) {
      *(buffer_ptr++) = *(argvn_ptr++);
    }
    // append \n and write buffer
    *buffer_ptr++ = '\n';
    syscall(SYS_write, STDOUT_FILENO, buffer, buffer_ptr - buffer);
    // next arg
    argvn_ptr = *(argv++);
  }
  // done
  syscall(SYS_exit, 0);
}

This is probably not what you expected to see. To be fair, the first version looped over argv and used printf. The C version is, however, supposed to be a C representation of the ASM. This version of C main uses the same algorithm as the following ASM. The following start.s uses the same system.inc.

@ start.s
.include "system.inc"
        .syntax unified
	.set ALIGNMENT,8
	.set BUFFER_SIZE,2048

.bss
	.comm buffer,BUFFER_SIZE,ALIGNMENT

.text
	.align ALIGNMENT
        .global _start
_start:
	nop @ for gbd breakpoint

	@ Intro Message
	@ sys.write(stdout, message, length)
	mov	r0,$stdout
	adr	r1,message
	mov	r2,$length
	sys.write

	@ Load Buffer via Global Offset Table
	ldr	r0,.Lgot	@ got_ptr = &GOT - X
	add	r0,r0,pc	@ got_ptr += X
	ldr	r4,.Lbuffer	@ buffer_offset
.Lpie0:	ldr	r4,[r4,r0]	@ buffer = *(got_ptr+buffer_offset)

	@ Write Args
	pop	{r0,r1}	@ pop argc, argvn_ptr = argv[0]
proc_arg:
	teq	r1,$0	@ if NULL != argvn_ptr
	beq	done
	mov	r2,r4	@ buffer_ptr = buffer
copy_char:
	ldrb	r0,[r1],$1	@ c = *argv_ptr++
	teq	r0,$0
	beq	output
	strb	r0,[r2],$1	@ *buffer_ptr++ = c
	b	copy_char
output:
	mov	r0,$0x0A	@ c = '\n'
	strb	r0,[r2],$1	@ *buffer_ptr++ = '\n'
	mov	r0,$stdout
	mov	r1,r4		@ buffer
	sub	r2,r2,r1	@ length = buffer - buffer_ptr
	sys.write
	pop	{r1}	@ argv_ptr = argv[n]
	b	proc_arg
done:
	@ sys.exit(0)
	mov	r0,$0
	sys.exit

@ Data needs to be in .text for PIE
@.data
message:
        .asciz "Args: [ASM]\n"
length = . - message
	.align ALIGNMENT

	@ Global Offset Table
.Lgot:
	.long	_GLOBAL_OFFSET_TABLE_-.Lpie0
.Lbuffer:
	.word	buffer(GOT)
	.align ALIGNMENT

The Makefile is more or less the same, but it has these changes.

ASM_TARGET=asm-arg-echo
ASM_PARAM=1 2
ASM_DEPS=system.inc
ASM_OBJ=start.o
ASM_LIBS=

C_TARGET=c-arg-echo
C_PARAM=1 2
C_DEPS=
C_OBJ=main.o $(CRT)
C_LIBS=-lc

Build and test both versions with the following commands.

make all
make install
make test

The output should be as follows:

$ make test
adb shell "/system/test/asm-arg-echo 1 2 && /system/test/c-arg-echo 1 2"
Args: [ASM]
/data/data/test/asm-arg-echo
1
2
Args: [C]
/data/data/test/c-arg-echo
1
2

The programs can be uninstalled as follows.

make uninstall

The GitHub repository has six projects. The hello world and arg_echo projects are listed above. There are a couple more versions of hello world. The puts_hello_world project links to libc and replaces the system call with puts(). The main_hello_world project goes a step furthur and uses an ASM main function and the CRT instead of a _start function. The interoperate project calls C, ASM and inline ASM from both C and ASM. The arg_sort project uses structs and malloc to sort command line arguments with a binary tree. The GitHub Makefiles have targets for working with GDB. NOTES.txt contains project notes and references.

Todo

EABI command line arguments (kind of pushed on the stack; _start and main are different) (EABI post?)
EABI function calls (first few parameters in registers, everything else on the stack) (EABI post?)
Position independent code / Global offset table / Procedure linkage table (probably another post)
GDB (probably another post)
Work more references into post

References:

Creating A Jekyll GitHub Pages Blog and Managing it With FreeBSD

2016-01-07T18:07:15+00:00

I have wanted a low maintenance technical blogging solution for a while. A Jekyll blog on GitHub Pages meets all of my criteria. Write posts in markdown, commit and push. The people at GitHub Pages will almost certainly keep the servers up.

These instructions are written for FreeBSD because that is what I use. The same general approach should work for any operating system.

Software Versions

$ date
January  8, 2016 at 03:07:15 AM JST
$ uname -a
FreeBSD mirage.sennue.com 11.0-CURRENT FreeBSD 11.0-CURRENT #0 r287598: Thu Sep 10 14:45:48 JST 2015     root@:/usr/obj/usr/src/sys/MIRAGE_KERNEL  amd64
$ ruby --version
ruby 2.1.8p440 (2015-12-16 revision 53160) [amd64-freebsd11]
$ jekyll --version
jekyll 3.0.1

Instructions

First, create a new GitHub repository named my_username.github.io, where my_username is your GitHub username. The repository needs to have “.github.io” at the end.

Next, install Jekyll, create a new blog and push it to github.

# install jekyll
su
portmaster devel/ruby-gems
gem install jekyll
gem install github-pages # optional, for local preview
exit

# create a new blog
# replace my_username with your username
# replace my_blog directory with your preferred project organization
cd # if you need to get $HOME
mkdir my_blog
cd my_blog
jekyll new my_username.github.io
cd my_username.github.io

# add ssh key to session using the sh shell
# assumes you are set up to use ssh
# use the following link to set up ssh
# https://help.github.com/articles/generating-ssh-keys/
sh
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

# add project to git and push to github
# replace my_username with your username
# use the https github url if ssh is not set up
# https://github.com/my_username/my_username.github.io.git
git init
git add .
git commit -m "Initial commit."
git remote add origin git@github.com:my_username/my_username.github.io.git
git remote -v
git push origin master

# configure blog
vim _config.yml

# save welcome post in drafts for future reference
# replace YYYY-MM-DD with the post date
# the archived welcome post can be deleted when it is no longer needed
mkdir _drafts
mv _posts/YYYY-MM-DD-welcome-to-jekyll.markdown _drafts/

# save default about in drafts for future reference
# the archived about file can be deleted when it is no longer needed
# customize about page
cp about.md _drafts/about.markdown
vim _drafts/about.markdown # remove permalink line, change layout to post
vim about.md

# create post
# replace YYYY-MM-DD the post date
# replace name-of-post with the title of the post
vim _posts/YYYY-MM-DD-title-of-post.markdown

# local build / test for errors
jekyll build --incremental --drafts

# local preview
jekyll serve --host 0.0.0.0 --port 4000 --drafts --watch

# sync changes
git add .
git commit -m "Change message."
git push