Asmutils would never become what they are without submissions from various hackers. As any open project, it relies much on contributions. Hence, if you've got an intention/inspiration to contribute something, you're welcome!
So, if you are the person who follows the challenge of UNIX assembly programming and wants your code to be included into asmutils, do examine this section carefully. It contains extremely important information, your contribution may not be accepted if you ignore suggestions below.
I think most of what is said in this section is evident to experienced developers of distributed free software, but if you are not the one, please read this carefully.
Before you begin make sure you are using the latest release of asmutils (available from the website), contributions based on old versions are (usually) rejected.
Usually, a good idea is to get current code from the CVS repository (cvs.sourceforge.net:/cvsroot/asm, module name is "asmutils"):
$ export CVS_RSH=ssh $ cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/asm login (when prompted for password, just press [Enter]. $ cvs -z9 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/asm co asmutilsThus you get the latest code for sure, as it may differ from the latest release. If you do not know how to deal with CVS, use the latest release.
So, get the latest asmutils code and look what is already done. Even if a program you want to contribute is not there, look at the ChangeLog, or contact maintainer first; it could happen that somebody is already doing (or has already done) what you're only going to do (ditto if you want to improve existing utils). This is very important! Asmutils are growing rapidly, do not duplicate effort of other hackers.
Here are few obvious requirements for the source code:
you should use nasm assembler
you should use supplied macro set
you should not use libc or any other external library
Note: I can accept utilities written in gas, but this will give me just more boring work of converting them to nasm syntax and asmutils macro set. This is to be avoided when possible. I mean, do it on your own :)
While writing your program take care of portability! Basically, this means:
no int 0x80 (or similar) calls directly, only sys_xxx macros
no ELF or kernel specific bizarre hacks, such as self-modifying code, writable CODESEG, etc.
no 0 instead of STDIN, 9 instead of SIGKILL, and so on
no OS specific calls, until a task can be done in a more generic way; try to use only POSIX/BSD syscall subset
I think you've got an idea. Just try to imagine your program on other OS, and ask yourself: what one will need to do make it run? what should I do to make compile on as many OSes as possible? If your program is not OS specific, try to set OS parameter to some other value (e.g. make OS=FREEBSD KERNEL=44) and see what happens. Even your program is OS specific (e.g. lsmod), at least try to make it readable.
| Warning |
Submissions that eliminate these simple rules are rejected. |
And of course, your code must do something useful, not just be written according to the above requirements :). Usual UNIX utils are preferred, but you can also contribute your very own program. Keep in mind that asmutils are not just fun. They are used in (and targeted on) small distributions and embedded systems. Thus, they should be as small as possible, use very few memory, and be as fast as kernel. Neither more, nor less.
When, finally, you think your program is ready, here again comes administrativia.
First, try to test your program. If it still works, rest a day, then look at it again.. I mean, I know you're very excited that your program works, but just try to look what now you can improve; do not send maintainer a new version every day, this will save him (and you) from the mess of versions.
Next, try to compile your program with different parameters from MCONFIG: at least compile it with different KERNEL and OPTIMIZE parameters. If your program is intended to be portable (which is recommended), also try another OS parameter. As a rule, compiling with OS=LINUX and OS=FREEBSD cleans out most (but not necessary all) issues. Also, be aware of code size difference when OPTIMIZE=SPEED and/or SYSCALL=LIBC are set -- explicit short jumps can became out of range. Nowdays a good idea is to use just jmp instruction, and let nasm take care of jump offset.
Try to include some documentation in the source. If your code uses 486+ instructions, please specify CPU requirements (especially if MMX, 3DNOW, SSE, etc are used) and use nasm CPU directive accordingly. Include comments along your code, especially around somewhat cryptic parts that are hard (as you feel) to understand initially. (but do not document every step, like xor eax,eax ;set eax to zero, etc).
New programs should be sent to project maintainer, while improvements of existing -- to particular util maintainer(s) first.
Since asmutils programs are usually quite small, please send full source of program instead of patches when possible; if you choose to send a patch, make sure that it is against the latest CVS version, i.e. do a checkout right before creating your patch, or create patch using cvs diff.
Sometimes maintainer will modify your code a bit. Please use that modified code for next program version.
Isn't it that simple? :)
With any additional questions refer to the asmutils website or contact asmutils maintainer.
asmutils are quite portable to any i386 (POSIX/UNIX) OS; if you are interested in asmutils running on your OS, I am willing to help. However of course I will need that OS, so you will have to donate me CD's (do not ask me to download gigs from the net!). Drop me a mail if you are interested.