Native Code Generation Overview

[dkinzer]

The ZBasic Reference Manual only briefly describes how code is generated for native mode devices by the ZBasic compiler. This post provides some additional details, including situations where external files with special extensions like .c, .S, .o and .a are involved. Knowledge of this process isn't required for programming native mode devices but the insight may be useful.

As described in the ZBasic Language Reference manual, you can include the special files with the extensions mentioned above in your project file. (Note that the ability to use conditionals in project files was implemented, in part, for this reason.) As the compiler processes a project file, when it encounters a .bas file, it compiles it to equivalent C code and stores it in a temporary directory (see the description of the --temp-dir option) in a file with a .c extension. When a filename with one of the special extensions (.c, .S, .o, .a) is encountered, the compiler notes its presence but does not attempt to process the content in any way.

Next, the compiler generates a "master include file", which has the same name as the project but with a .h extension, which is included in every generated .c file. The master include file contains extern declarations for all public variables and C prototypes for all public subroutines/functions.

Finally, the compiler generates a makefile which contains the names of all of the generated .c files as well as all of the special external files. The .c and .S files are included in the "source list" and the .o files are included in the "object list". The link command in the generated makefile refers to the names of all of the object files along with the external .a files and the ZX runtime library, of which there is one for each device. The ZX runtime library for the ZX-24n is named libzx24n.a.

When the make process is invoked, it runs the avr-gcc compiler for each source file (with different options depending on whether it is a .S or a .c file) and then, assuming there were no errors, it runs the avr-gcc linker to produce a native executable file. The latter is then transformed into a ZX native downloadable file and all of the intermediate files are deleted (but see the compiler option --keep-files).

For special purposes, there is a way to specify additional options to be passed to the compiler/linker so that you can override "standard" options or add to them. See the description of the --gcc-opts options for more details.

The installer for the updated ZBasic compiler installs a subset of the WinAVR avr-gcc files along with the usual other files. This is done in a way that will not interfere with any existing WinAVR installation that you might have on your system. Moreover, when the ZBasic compiler invokes avr-gcc components, it does so in a way that ensures that the existence of a different WinAVR installation on your system does not affect the process.

We plan to produce several application notes dealing with advanced topics related to native mode programming. They will be announced here when they are available.