Coding
This is the FreeDOS Coding How-to and describes the basic coding standards of the FreeDOS Project.
Copyright and copyleft
The simplest way to make a program free is to put it in the public domain, uncopyrighted. This allows people to share the program and their improvements, if they are so minded. But it also allows uncooperative people to convert the program into proprietary software. They can make changes, many or few, and distribute the result as a proprietary product. People who receive the program in that modified form do not have the freedom that the original author gave them; the middleman has stripped it away.
In the FreeDOS project, our aim is to give all users the freedom to redistribute and change FreeDOS software. If middlemen could strip off the freedom, we might have many users, but those users would not have freedom. So instead of putting FreeDOS software in the public domain, we “copyleft” it. Copyleft says that anyone who redistributes the software, with or without changes, must pass along the freedom to further copy and change it. Copyleft guarantees that every user has freedom. Copyleft also provides an incentive for other programmers to add to free software. Important free software projects such as the FreeDOS Project exist only because of this.
Copyleft also helps programmers who want to contribute improvements to free software get permission to do that. These programmers often work for companies or universities that would do almost anything to get more money. A programmer may want to contribute her changes to the community, but her employer may want to turn the changes into a proprietary software product. When we explain to the employer that it is illegal to distribute the improved version except as free software, the employer usually decides to release it as free software rather than throw it away.
To copyleft a program, first we copyright it; then we add distribution terms, which are a legal instrument that gives everyone the rights to use, modify, and redistribute the program’s code or any program derived from it but only if the distribution terms are unchanged. Thus, the code and the freedoms become legally inseparable.
Proprietary software developers use copyright to take away the users’ freedom; we use copyright to guarantee their freedom. That’s why we reverse the name, changing “copyright” into “copyleft.”
Copyleft is a general concept; there are many ways to fill in the details. In the FreeDOS Project, we suggest that you use the GNU General Public License (GNU GPL). However, the ultimate choice of what copyright/copyleft to use is up to you.
Applying the GNU GPL
This section is adapted from the GNU GPL version 2.
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. In the FreeDOS Project, we suggest that you use the GNU General Public License (GNU GPL). However, the ultimate choice of what copyright/copyleft to use is up to you.
To apply the GNU GPL to your program, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the copyright line and a pointer to where the full notice is found.
<one line to give the program's name and a brief idea of what it does.> Copyright (C) <year> <name of author> This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
The hypothetical commands “show w” and “show c” should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than “show w” and “show c”; they could even be mouse-clicks or menu items—whatever suits your program.
You should also get your employer (if you work as a programmer) or your school, if any, to sign a Copyright Disclaimer for the program, if necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' written by James Hacker. <signature of Ty Coon>, 1 April 1989 Ty Coon, President
The General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.
What to say and what not to say
You should avoid using the term “freeware” when referring to your programs. This term has no clear meaning today, and can mean anything from “the program is free, but you can’t have the source” to something like “in the public domain.” Similarly, avoid the term “free software” when its meaning may be unclear. Instead, state directly what the copying and redistribution restrictions are, if any. If you are releasing your program into the public domain, say so.
Please also avoid referring to a program as being a "clone" of another program. You can say that a program works in a similar way to another program, but please do not use the word "clone" when comparing one program to another. FreeDOS is not a "clone" of any other DOS, it works like other DOS operating systems.
If you wish your program to be distributed under the GNU General Public License, apply the proper text to your source files, include the GNU GPL as the file COPYING, and explicitly state in your documentation that your program is distributed under the GNU GPL.
The worst situation you can get yourself into is to not clearly state how your program may be used, and then have someone come along and claim your code as their own.
Crediting others
If someone else sends you a piece of code, and you use it in your program, you must fully document where you got it. Include the other person’s name and email address, and any other appropriate contact information. If you found someone else’s code, and you wish to include it in your program, then things get a little tricky. It would be far easier if everyone wrote software using a license like the GNU GPL, but they don’t. Therefore, you need to be careful about what you include in your source code.
Make sure the other person’s code allows you to incorporate it into your own program. If the other program is in the public domain, then it is probably okay. If it is freeware, it may be or it may not.
You should make all efforts to contact the original author before you include any foreign code into your program. Have the original author send you a document, if possible, explicitly giving you permission to use his code in your program.
When you incorporate the other person’s code, always give full credit. Never claim someone else’s work as your own. This is not only unethical, but you will likely wind up in some kind of legal trouble later on down the road. So don’t use anyone else’s code without giving full credit.
The following is usually acceptable when referring to someone else’s code:
/* this bit contributed by John Doe, john@example.com */
Or this:
/* This code was lifted from BAZ, but John Doe, john@example.com However, I have not been able to reach John at this address, but the BAZ program was released under the GNU GPL ... */
Programming languages
We prefer that all FreeDOS programs be written in either C or Assembly. Certainly all Base FreeDOS programs (those programs that reproduce the functionality of MS-DOS) should be written in either C or Assembly, as indicated by the FreeDOS Spec.
All program libraries that you use to create your program should also be open source projects. Please check the redistribution restrictions for your program. If the libraries are not open source, then others may have trouble obtaining the libraries and, hence, in building your software.
You should make all efforts to use an existing library before writing one of your own. For example, the GNU getopt library has already been written by the Free Software Foundation to help you parse a command line in C programs. Other libraries also exist for language internationalization and console I/O.
If we all use the same libraries, then the overall maintenance of our FreeDOS programs will be much easier. By updating one library, we can extend the functionality of all FreeDOS programs that link with it.
C code should be indented using the GNU indent program, using the -gnu option. Let the program do the work for you. However, we do not have any indentation standards for Assembly or other languages. Please use good judgement, and use indentation that others can easily read.
We prefer that you write all FreeDOS programs using the ANSI standard for your compiler, so that your code is instantly portable to any compiler. However, we recognize that is is often impossible. Therefore, any compiler-specific functionality that is used in your program should be well documented. This will aid someone else when they try to build your program using a different compiler.
The following is one example in how to document a compiler-specific function:
/* "Halt and catch fire" instruction, uses Microsquish C */
/* usage is: int _hcf(method) where method is WARM_BOOT or COLD_BOOT */
if (user_wants_to_reboot) {
_hcf(WARM_BOOT);
}
Ideally, all compiler-specific functionality should be encapsulated using #ifdef statements, using proper conditionals that allow the program to build using a variety of compilers. For example, the following is one way to use these statements to support different compilers:
#ifdef _FOO_C long_wait(1); /* C compiler by Foo Corp. */ #else ...
Usage statements
This section is adapted from the GNU GPL version 2.
All programs should use the same format when printing their usage statements. This presents a more consistent interface to the user, and lets people find information in the same place in every program.
The /? command line option should always display a usage statement, and then the program should immediately exit. Programs should use this format to display their usage:
NAME - one-line description of what the program does Usage: ... Options: ...
For example, the following might be the usage for the CHKDSK program:
CHKDSK - Check the disk for errors chkdsk [d:] [options] Options: /F Fix errors on the disk when found /V Display the name of every file as the disk is checked If no drive is specified, check the current disk for errors.
If your program has more than one possible synopsis of usage, then you should display them both. For example, the JOIN program:
JOIN - Join a drive to a directory join d: d:path join d: /D Options: d: The drive letter you want to set up d:path The full path which will be assigned to the drive /D Delete this join definition
If you wish to display your copying policy in your usage statement, please be brief as a long copying policy can take up valuable screen real estate. One or two lines would seem appropriate. The following might be one way to announce that your program is distributed under the GNU General Public License:
Gnomovision version 69, Copyright (C) 2000 James Hacker This program is free software (GNU General Public License) Usage: ...
For other copying policies that you wish to announce in your usage statement, please use a similar syntax.
External documentation
All programs should be well documented using external documentation files. The following are the minimum that we request for any source distribution:
README
This file contains a description of the program, and should also contain a description of the copyright and redistribution restrictions, if any.
INSTALL
This file should explain, in detail, the compiler used to build the program, and the exact steps that are required to build your program. If your program requires that other libraries be downloaded and compiled first, document this here.
HELP
The Help file should be in the style of Unix man pages, which is as follows:
NAME One line to describe the program SYNOPSIS Sample usage for your program, showing all possible command line options. DESCRIPTION An in-depth discussion of your program, which should also describe how the program may differ from other DOS versions. EXAMPLES Sample command lines, if appropriate. BUGS A list of show-stopping or obvious bugs, if any. AUTHOR/CONTRIBUTORS A list of anyone who contributed to the program. COPYING The license terms under which the program may be copied or redistributed.
NEWS
This file contains a description of the changes over the program’s revision history. You should document what features were added/removed in each release, and what the release version was. Also include the date the software was made available for download, and any other information that seems appropriate.
LICENSE or COPYING
This file contains a copy of your copying license. Put nothing else in the license file. If your program is in the public domain, then say so in this file. If you use the GNU GPL, then copy the GNU General Public License to this file. You should state your redistribution license in a file named either COPYING or LICENSE, which will make it easier for someone to find your copying policy.