The "Go" tools

for those new to ....

by Jeremy Gordon -

This file is intended for those interested in 32 bit assembler programming, in particular for Windows.

One of the most obscure things to many people is how it is possible to write and create a program which the computer can then execute. In quick start to making a simple Windows program we took away some of the mystery about this and saw how simple it is to do, particularly with the assembler development tools. That was just a brief overview. Now I am going to describe the build process and the files involved in more detail.

Making a program

The process for Windows programming using assembler (without resources) is:-

The process for Windows programming using assembler (with resources) is:-

The .asm file

This is a file which you make and edit using an ordinary text editor, such as Paws which you can download from my web site, www.GoDevTool.com, or a program like Notepad or Wordpad which comes with Windows. If you use Notepad or Wordpad you should make sure you save the file in a format which adds no control or formatting characters, other than the usual end of line characters (carriage return and line-feed). This is because the development tools only looks for plain text. You can achieve this by saving the file as a text document. If you don't use an extension for the file (the extension is the characters after the "dot") then the editor may give the file a ".txt" extension but you can change this by renaming the file (you can rename the file by right-clicking on the name using Windows Explorer or My Computer).
It may be that you cannot see the extension on your computer, but it may be set that way. To see the extensions of your files from Windows Explorer, choose the menu item "View", "Folder options", then the "View" tab and ensure that the "Hide file extensions for known file types" is not checked.
It is traditional amongst programmers to give their source scripts an extension which matches the language in which the source code is written. For example you might have an assembler file called "myprog.asm". Similarly you will usually find source code written in the "C" language with the extension ".c" or ".cpp" for "C++", ".pas" for pascal and so on. However, there is no magic in these extensions. The Assembler will accept files of any extension.
The .asm file contains your instructions to the processor in words and numbers. These are executed by the processor when the program is run. It is said, therefore that the .asm file contains your "source code" or your "source script".
When you are ready to make your program, you pass the .asm file to the Assembler which is a program which converts .asm files to .obj files. You could use, for example, my assembler GoAsm.

The .obj file

This is a file made by the Assembler from an .asm file. The Assembler takes the instructions in the .asm file which are in words and numbers and converts them into the COFF object format which is a format that the linker expects. The Assembler concatenates all your code and data instructions in the source code and puts them into code and data sections in the .obj file. The code section contains the actual processor instructions ("opcodes") which the processor executes when the program is run. The data section contains information which will be held in memory while the program is run.
You can't actually run an .obj file as a program, because it is not in the final program format expected by Windows (the PE format). You pass the .obj file to the Linker when you are ready to make your program. Sometimes the .obj file is called a "binary" file or "bin" for short. This is because the file can properly be regarded as now containing only numbers. But if you look inside an .obj file you will still see the strings of characters that were in your source script.

The .rc file

This is a another text file which you make using a text editor. In this file you provide the instructions in words and numbers which Windows uses to make the resources (mostly menus, dialogs and stringtables) in your program when it is run. You can also use the .rc file to name files which must be loaded into the .res file when the Resource compiler is run (such as, for example, icons bitmaps and cursors). Therefore the .rc file can properly be described as containing source material. You can find more information about resources in the manual that accompanies my resource compiler GoRC.

The .res file

This is a file made by the Resource compiler from an .rc file. The Resource compiler formats the instructions in the .rc file which are in words and numbers and converts them into a form ready for insertion in the resource section in the final .exe file.
You pass the .res file to the Linker when you are ready to make your program.

The .exe file

This is the final executable file which can be run as a program by Windows. It is in the Portable Executable (PE) format. The file is made by the Linker which takes one or more .obj files and a .res file and combines them into the final .exe file. The PE format also requires that the .exe file has a header with information about the .exe file. The Linker provides this information. To make Windows programs you will need to use a linker capable of making PE files, for example GoLink.

The .dll file

This file contains other functions and data which your .exe file can use when it is running. Most of the time you won't need to use a .dll file at all. However, a .dll file is useful if you have functions which need to be called by more than one .exe file. Instead of duplicating the code in the two .exe files you can have it only once in a .dll file. Windows uses .dll files extensively to provide access to the APIs to Windows applications. Have a look in the Windows\system folder in your computer - this is where the Windows Dlls are normally kept.

Organizing your programming work

I'm going to suggest how you may organize your programming work. There are other ways, including the use of an IDE (Integrated Development Environment) to run the programs for you. But if you are just starting you will probably find it easier to follow my suggestion to start with and change it to suit your own needs and ideas.

It needs a bit of setting up, but once this has been done you have a flexible formula which can be used over and over again and can easily be altered as required.

Firstly I would keep all programming work and files on the hard disk in a folder called something like PROG. This separates them from other work on your computer.

Then on starting a new project, I would suggest you create a new sub-folder for that project, using the "File", "New" menu item in Windows explorer. Keep the source files for the project and all files created from those source files in the sub-folder. So all .asm, .rc, .obj, .res and .exe files for the project will be in the sub-folder.

Keep the Assembler, Resource Compiler and Linker programs in another sub-folder in the PROG folder.

So, for example, if your project is called "Myprog" your files would be organized as follows:-

• In the folder c:\prog\myprog - Myprog.asm, Myprog.rc, Myprog.obj, Myprog.res and Myprog.exe.
• In the folder c:\prog\utils - GoAsm.exe (the Assembler), GoRC.exe (the Resource compiler) and GoLink.exe (the Linker).

If you are using resources, the first batch file may be called "Gorc.bat" and will have the job of starting the resource compiler so that the file Myprog.rc will be converted to Myprog.res. In this case there will be a single line in the batch file as follows:-
c:\prog\utils\GoRC /r Myprog.rc
If you use this file and type "Gorc" and press enter from the command line, it will be as if the full command line had been entered.

The main batch file may be called "Go.bat" and is the one which causes Myprog.asm to be assembled and then the resulting .obj file and the .res file to be converted into the .exe file. In this case there will be two lines in the batch file as follows:-
c:\prog\utils\GoAsm Myprog.asm
c:\prog\utils\GoLink @command.fil

The first line starts the assembler and causes Myprog.obj to be made.
The second line starts the linker. You can see that here we use a file with the name "command.fil". This is a file which contains instructions for the linker. Using a command file makes it easier to change the parameters passed to the linker. You make this file using the text editor. Again it should be in the "c:\prog\myprog" folder.

The command file might contain the following lines (for example):-
/debug coff
Myprog.obj
Myprog.res
Kernel32.dll

The first line here tells the linker to include symbols in the final executable. This will allow you to use the symbolic debugger, GoBug. The next two lines give the linker the input files, in this case the object file and the res file containing the resources (omit the .res line if you are not using resources). The last line tells the linker to look in the system file Kernel32.dll to identify API calls made in the program. This is a necessary part of the linking process. It may well be that your program makes calls to APIs which are in other system Dlls. If so those Dlls need to be specified as well. You can find out which Dll contains the API which you are calling because this information is contained in the Windows information in the Software Development Kit, or in the Windows header files. Usually most of the API calls you will want to make are contained in one or more of the following Dlls (in addition to Kernel32.dll), which could also be put in the command file:-
user32.dll
gdi32.dll
COMCTL32.dll
COMDLG32.dll
OLEAUT32.dll
Winspool.drv
Hhctrl.ocx
The linker may run more quickly if you can reduce the list.

Note: the above works with GoLink but other linkers require you to use "lib" files to identify the relevant Dll. If the lib files are not available you have to make them from the Dll using a special tool.

Running the Assembler, Resource Compiler and Linker

There are two ways to run the batch files you have made.

The first way is to double click on the appropriate file icon in Windows Explorer (which opens a console window to give the results).

The second way is to open an MS-DOS (command prompt) window yourself and run the files from there. To do this click start, programs, MS-DOS prompt (in XP this is start, all programs, accessories, command prompt). You will then probably see the prompt "C:\WINDOWS>". This means that the current folder is the "Windows" folder in drive c:. Change the current folder by typing "cd c:\prog\myprog" and pressing the enter key. The prompt should now say "C:\prog\myprog>". Assuming your source files are in order you are now ready to run the batch files. "Gorc" will run the resource compiler (if you are using this), "Go" will assemble and link the program. Finally "Myprog" will run the exe.

See the file Resource.htm in GoRC's documentation to see how to make an RC file.
See the file GoAsm.htm in GoAsm's documentation or click on GoAsm.chm to see how to make a working .asm file.
See the file GoLink.htm in GoLink's documentation to see more about using the linker.
There are various sample files on my site for you to look at and use, in particular the HelloWorld sample files and the help files to Testbug, and in the GoAsm and GoLink documentation.