AmiWest Setup

Setup

Developing software on and for AmigaOS involves three major components: the AmigaOS SDK or "Software Development Kit", a source code Editor and your imagination.

The first part of this equation, the AmigaOS Software Development Kit or AmigaOS SDK, is a collection of files and tools that will convert your source code into an Amiga application. The SDK consists of a collection of the latest documentation, "include" files, example code, utilities and the GCC compiler. With each major version of AmigaOS a new SDK is issued that allows developers and their applications take advantage of the latest OS features.

The second part of the equation is a means to edit and manage your programming project and its source code. While you can edit source code in the AmigaOS NotePad text editor, there are much better & easier ways. The most powerful programming environment on AmigaOS is called CodeBench. In addition to providing a source code editor that provide syntax highlighting, help as you type and context sensitive help, CodeBench takes care of building "makefiles", runs the compiler, collects & presents errors and can interact to remote source code servers.

Finally there is you! Obviously, developing AmigaOS applications with the SDK requires a working understanding of the C language. To take advantage of the specific powers of AmigaOS, there are more methodologies and functions to learn. The SDK provides a number of example programs to learn from and a bounty of "autodocs" that document AmigaOS functions. Every day there are new things to learn.

Installing the SDK

The latest version of the SDK can be downloaded from the Hyperion Entertainment SDK webpage.

Once downloaded, you can double-click on the SDK archive file to use the AmigaOS Unarc utility to decompress the SDK to your RAM Disk. This will create a directory that includes all the SDK files to be installed.

In that directory you will find the Install SDK installer program. If you run that, it will ask you what you want to install and for a location to install to. Unless you have a severe limitation on hard disk space, it's recommended you make a "Full" install. As part of the install process, a few commands will be added to your "user-startup" script to assign SDK: to your system.

Once the SDK installation is complete, your SDK: path will include the following directories:

• Documentation - This drawer contains various documentation, AutoDocs, and other information related to the SDK. It also contains documentation on the various tools and compilers.

• Examples - This drawer contains example source code on how to program for AmigaOS 4.x. Examples are sorted by theme/topic.

• Local - The Local drawer is our means of isolating the compilers and third-party additions. See SDK documentation PDF file for more information on the Local drawer.

• gcc - The gcc drawer contains the GNU C/C++ compiler. It is set up in a way that there are no user-serviceable parts inside. This makes it easy to exchange the compiler when later versions become available.

• Include - This drawer contains system-level include files. Like the gcc drawer, it should not need to be modified.

• Contrib - The Contrib drawer contains various files that where contributed to the SDK. Among other things, it contains the latest source code for the static C runtime library clib2.

You can test the installation of SDK and its GCC compiler by opening a shell and typing the following command:

gcc --version

This should cause a text to be printed by the compiler, including the version number.

Testing the SDK

Open the NotePad text editor and type the following text:

#include <proto/dos.h>
 
int main(void)
{
 IDOS->Printf("Hello, World\n");
 return 0;
}

Then save the file to "hello_world.c" and go back to the shell, CD to the directory with your file and enter this command:

gcc -o hello_world hello_world.c

After a few seconds, the gcc compiler should return. As long the source was correctly entered and no errors or warnings were displayed by GCC, then you will have successfully compiled your first Amiga program. Just type "hello_world" into the command line to see it run. Congratulations!

Installing CodeBench

You may have used the NotePad text editor and your Shell console to create the sample C program above, but there are much better ways to edit and compile C programs. Such development systems provide more specialized editors suited for coding and means for managing compilation, handling warnings and errors, etc.

On AmigaOS we have CodeBench to improve and automate our coding sessions. CodeBench provides a text editor with "syntax highlighting" which means that it color-codes text on the basis of what it is: comments, commands, strings, etc. CodeBench also provides a GUI for GCC - click a button to compile, review the results in a window. There are even more features for more serious projects.

CodeBench can be downloaded from the website of the developer, SImon Archer. Once downloaded, you can double-click on the archive to open it in the AmigaOS Unarc utility and decompress the files to your RAM Disk. Once finished, you will find an "Install CodeBench" installer program icon. When you run the installer, it will confirm whether you are upgrading or making a new install and ask you for a location.

Once this process is done, you're ready to start a project in CodeBench. CodeBench comes with comprehensive documentation on itself in web format (that can also be accessed here).

Testing CodeBench: Hello World

The first thing you can do with CodeBench is to start a test project to how things work. At this page you can find information on on starting a project. Basically, it's a matter of clicking the Start Project button, setting a few names and variables and entering a path for your project.

Once the new project is established, then you can use the "Editor/Create New File..." menu item to start a new source file. If you copy the above "Hello World" source code and paste it into the editor and save the source as "hello-world.c" then you will be ready for compiling.

In the CodeBench tool bar window, click the green "Build" button and CodeBench will automatically prepare, compile and link your project into an executable program. A Build window will appear that will show the status of the building of your project. Assuming your code compiles without errors, you will then see a Run button with a play icon in the CodeBench toolbar. Clicking that button will bring up a window to let you run your program.

Testing CodeBench: Hello with a GUI

Once you start coding with CodeBench, you will find it provides a number of aids to help with coding: such as highlighting or coloring the source code by type, letting you work with a number of sources at one time, letting you access AmigaOS documents by shift-double-clicking on AmigaOS functions and providing a quick way to track compiling errors into the source code.

With CodeBench you can easily jump into more advanced coding, such as our old "Hello World" program with a modern GUI. Just copy and paste the following source into a new project and try to compile it:

#include <dos/dos.h>
#include <classes/window.h>
#include <gadgets/button.h>
#include <gadgets/layout.h>
#include <images/label.h>
 
#include <proto/intuition.h>
#include <proto/exec.h>
 
int main(void)
{
    // Create a window with a label and button.
 
    Object* winobj = IIntuition->NewObject(NULL, "window.class",
        WA_Title, "Hello World Example",
        WA_Activate, TRUE,
        WA_DepthGadget, TRUE,
        WA_DragBar, TRUE,
        WA_CloseGadget, TRUE,
        WA_SizeGadget, TRUE,
        WINDOW_Position, WPOS_CENTERMOUSE,
 
        WINDOW_Layout, IIntuition->NewObject(NULL, "layout.gadget",
            LAYOUT_Orientation, LAYOUT_ORIENT_VERT,
            LAYOUT_SpaceOuter, TRUE,
            LAYOUT_DeferLayout, TRUE,
 
            LAYOUT_AddImage, IIntuition->NewObject(NULL, "label.image",
                LABEL_Text, "Hello, World",
                TAG_END),
 
            LAYOUT_AddChild, IIntuition->NewObject(NULL, "button.gadget",
                GA_RelVerify, TRUE,
                GA_Text, "Quit",
                TAG_END),
           TAG_END),
        TAG_END);
 
    if (winobj != NULL)
    {
        //  Open the window.
        struct Window *window = (struct Window *) IIntuition->IDoMethod(winobj, WM_OPEN);
 
        if (window != NULL)
        {
            // Obtain the window wait signal mask.
 
            uint32 signal = 0;
            IIntuition->GetAttr(WINDOW_SigMask, winobj, &signal);
 
            // Input Event Loop
 
            BOOL done = FALSE;
 
            while (!done)
            {
                uint32 wait = IExec->Wait(signal | SIGBREAKF_CTRL_C);
 
                if ( wait & SIGBREAKF_CTRL_C )
                {
                    done = TRUE;
                    break;
                }
 
                if ( wait & signal )
                {
                    uint32 result = WMHI_LASTMSG;
                    int16 code = 0;
 
                    while ((result = IIntuition->IDoMethod(winobj, WM_HANDLEINPUT, &code)) != WMHI_LASTMSG)
                    {
                        switch (result & WMHI_CLASSMASK)
                        {
                            case WMHI_GADGETUP:
                                done = TRUE;
                                break;
 
                            case WMHI_CLOSEWINDOW:
                                window = NULL;
                                done = TRUE;
                                break;
                        }
                    }
                }
            }
        }
 
        /* Disposing of the window object will also close the window if it is
         * already opened and all attached objects.
         */
        IIntuition->DisposeObject(winobj);
    }
 
    return RETURN_OK;
}

Once you have built and run this example program the following GUI will be produced: