An Overview of the Code Generation Process

[dkinzer]

Some questions have arisen as to how the ZBasic compiler generates a native code download file, especially when external files with special extensions like .c, .S, .o and .a are involved.

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.) When 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). When a filename with one of the special extensions 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. The description of this option is not in the documentation that you have access to.

The installer for the updated ZBasic compiler will install 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. 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 does not affect the process.

[mikep]

Some questions have arisen as to how the ZBasic compiler generates a native code download file, especially when external files with special extensions like .c, .S, .o and .a are involved....

I would like to see some form of this description in chapter 4 to replace the first paragraph of section 4.1 but in its own new section (probably before the existing 4.1). A picture might even be appropriate - see my ZBasic picture as an example.