# Asmutils HOWTO

### Konstantin Boldyshev

Linux Assembly

`<konst@linuxassembly.org>`

Version 0.9

Copyright © 1999-2006 Konstantin Boldyshev

$Date: 2006/02/18 10:08:03 $

This is the Asmutils HOWTO.

This document is to accompany asmutils, explain asmutils internals, describe how to write asmutils program and how to contribute to the project.

It targets asmutils developers and advanced users striving for the secret lore of the assembly entity.

# 1. Introduction

## 1.1. Legal blurb

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License Version 1.1; with no Invariant Sections, with no Front-Cover Texts, and no Back-Cover texts.

## 1.2. Before you begin

I assume you are familiar with UNIX and assembly language to an extent when you are able to understand what is written here. If you are unable to comprehend most of it, then probably this manuscript is not for you, sorry.

Also, I expect you to dig in and examine source code of asmutils. This document is not intended to replace the source, its goal is only to accompany asmutils source and explain several unclear moments. Again, examine ALL source code. Look how command line parsing is done, how conditional assembly for different kernel versions is done and so on -- I am not going to explain all and everything here.

Okay, enough ranting. This document deals with compiling, developing, debugging, contributing issues, it shows some tricks you can use; also it describes a set of macros I've developed to write fast and readable, that are hiding from you unneeded details and take care of optimization.

You may also want to read other documentation represented at the Linux Assembly site to get better general (not asmutils specific) understanding of asmutils source code.

## 1.3. Compiling asmutils

Asmutils are build with the usual compile suite and nasm. Except nasm you will need GNU make, ld, sh, ln, rm, possibly strip and possibly something else, depending on your target OS.

Preferred program versions are:

- nasm 0.98.39

- ld from GNU binutils 2.13

- GNU make 3.79

Older/newer/other versions may work too. GNU make is required, on BSD systems it is usually called gmake, and can be found in ports collection.

All compile-time configuration is in the `MCONFIG` file, which has enough comments to figure out what you can do. You can try to fallback to libc functions instead of using direct system calls by defining `SYSCALL=LIBC` in `MCONFIG` if your really want to do so; then you will also need gcc and libc headers.

> Note: Well, to be sincere, if you set `SYSCALL=LIBC` do not expect it to work out-of-the-box, even if it compiles flawlessly. Instead, prepare to hack `MCONFIG` (hint: `STARTUP=y` may help if startup stack differs from usual), `.inc` files and source code to animate this malformation. After a couple of sleepless nights you may understand that it is impossible to get things right -- you are bypassing libc headers, and on various libc versions miscellaneous functions can be implemented as macros, or can be just missing (e.g. getdents on glibc 2.2.x). You may find out that sometimes libc function which has the same name as some system call is not what you think of it. Also, expect any other kind of disaster and affliction when trying to run what you have built after all, especially on weird systems like BeOS or QNX (hint: check constants in `os_yourOS.inc`). Finally, find yourself on the brink of suicide, screaming and pulling out your hair, and devising your all to developers of your libc. They say, life ain't easy.

> Now that being said.. Some (and perhaps most of) utilities will compile and work as usual.

> Also, note that building asmutils libc with `SYSCALL=LIBC` is not a hmm.. reasonable idea at all.

> Note: Several utils (cpuinfo, eject, httpd, kill, etc) have their own additional configuration in the source code.

> Note: You can easily cross-compile asmutils. With `ELF_MACROS` you will even not need a linker, without them linker must support target OS executable format.

> Note: On BSD system you may try Linux emulation to run Linux binaries, but as a rule native binaries will do the job better.

|  | Next
|  | Program layout