boldinventions.com

KCMD Command Processor Documentation - Getting Started 3

<-- PREV PAGE blank space NEXT PAGE -->

Now that all the source files are added to the project, we can try building. Go to the Build menu and select 'Build Solution'.

You should get an output window filled with messages like:

fatal error C1189: #error : No Platform Symbol Defined.

This is because we did not tell KCMD which platform we are using. To do this we need to define a C Preprocessor macro. This means opening the project settings again. So we select Configuration Properties, then C/C++, then PreProcessor on the left pane, and then click on the Preprocessor Definition Line on the right pane, and we add the characters:

;WIN32_CONSOLE

to the symbols which are already defined. In the picture below, what we added is highlighted in blue. Do not miss the semi-colon in front of the WIN32_CONSOLE. There should be no spaces or other characters.

msvc2008-adding-win32console-ndefine

Press OK.

Now, every source file which gets compiled will have the WIN32_CONSOLE symbol defined. This will cause kcmd to use the include file kcmdPort_WIN32_CONSOLE.h to be included when we build.

Now try building again. It should now build all the sources, including all the kcmd sources, and not give any errors. If you run the program now, it will still just be a hello-world program however. ALthough the command processor is compiled, we aren't calling it or initializing it.

The next step is to create the low-level character IO functions for the command processor. First we define the very simple functions. We will use the KCMD types for characters, which is KCHAR.

The following function definitions go into main.c, before the function called main().

KCHAR conio_getc(void)

{

return _getch();

}

void conio_putc(KCHAR ch)

{

putc((int) ch, stdout);

}

int conio_kbhit(void)

{

return _kbhit();

}

int conio_puts(KCHAR *pStr)

{

fputs(pStr, stdout);

return 1;

}

After defining these IO functions, we need to call the KCMD processor to initialize it. In the main() function, after printf("Hello, World\n") line, we add a call to kcmd_init():

init_kcmd(KCCSTR("\r\nPROMPT> "),

NULL,

conio_getc,

conio_kbhit,

conio_putc,

conio_puts);

Now the project should compile and even run, but it still is just a hello, world application. The command line processor is getting initialized, but we have yet to ask it to collect any or process any command lines.

/*

* Loop forever getting input lines from the input device and

* processing the command lines.

*/

do

{

iExitFlag=process_kcmds(1);

} // Do-while loop

while(1!=iExitFlag);

Make sure you define iExitFlag as an integer variable at the beginning of the main() function:

And now it compiles. However it does not yet run. There are no commands defined at all, so it will generate an exception when an unitialized pointer is used. To add commands, we need to include my_commands.h. There is a template for the my_commands.h file located in the trunk folder which contains all the other sources. We call this a template because instead of simply including this file in the project, we want to make a copy of it and place the copy in our project folder. Then we will customize it just for this project.

Copy the my_commands.h file into the project. Make sure it goes into the same folder within our project as main.c. Then right-click on the 'Source Files' and 'Add Existing Item' to include this in the sources.

my_commands.h is used in a non-standard way. Global structures are defined and linked together in a list by preprocessing macros. This is how commands could be defined in such a way that all the code for the command is in one spot, and yet the command can be part of a linked list of structures compiled into program memory.

So it is very important to only include my_commands.h ONCE from ONE source file, such as main.c. Otherwise you will get errors as the linker is faced with many global structures with the same name

#include <stdlib.h>

#include <stdio.h>

#include <string.h>

#include <conio.h>

#include "kcmdIncludes.h"

#include "my_commands.h"

Now the includes at the beginning of main.c should look like this.

And it... does not compile...

my_commands.h(49) : fatal error C1083: Cannot open include file: 'my_custom_commands.h':

my_custom_commands.h is missing, because we don't have any custom commands yet. For now we can comment out line 49, so it doesn't try to include this non-existent file. Later when we want to start making our own custom commands we can make a new include file to put here.

/****************************************************************************

* Here is where more include files with more commands would be added.

* Simply follow the model of kcmd_basic_commands.

****************************************************************************/

//#include "my_custom_commands.h"

So we comment out line 49. And try to build again.

It should build without any more errors.

Now try to run by going to the Debug menu and select 'Start Debugging'.

msvc2008-its-alive

So type help and hit enter.

The kcmd command processor should now be functioning. It may have seemed like a lot of steps, but we did go into detail about each little step.

Next, we need to learn how to use it.

<-- PREV PAGE blank space NEXT PAGE -->