VBCC Proprietary Functions and Features
This document lists all proprietary, non-standard, and Amiga-specific features, functions, pragmas, attributes, and startup code options available in VBCC (including vclib and Amiga targets).
Startup Code Options
VBCC provides several startup code options and files for Amiga targets:
Startup Files
| File | Description | Usage |
|---|---|---|
| `startup.o` | Standard C startup code | Default startup for most applications |
| `minstartup.o` | Minimal startup code | For small/embedded/resident programs |
| `resident.o` | Resident program startup | For programs that stay in memory |
| `amiga.lib` | Amiga-specific library | For AmigaOS system integration |
| `auto.lib` | Amiga auto-open/close library | For automatic library management |
Startup Options
| Option | Description | Effect |
|---|---|---|
| `-nostartup` | Don't link startup code | Manual startup code required |
| `-nostdlib` | Don't link standard library | Minimal linking |
| `-resident` | Resident program | Make program resident in memory |
| `-minstartup` | Use minimal startup code | Smaller binary, less initialization |
Application-Specific Startup Configurations
1. Minimal Amiga Command (No Command Line Parsing)
Use Case: AmigaDOS commands that need maximum performance and minimal overhead, handling their own arguments with ReadArgs, workbench startup, and ctrl-c signals.
Startup Code: minstartup.o (minimal startup)
Entry Point: main(char *command) or main(void)
Compiler Options:
- -nostdlib (for minimal linking)
- -sc -sd (small code, small data)
- -resident (for residentable executables if needed)
Static Libraries:
- vlibos3:amiga.lib (Amiga library only - no vc.lib)
Why Use This: minstartup.o provides the smallest possible startup overhead. It does NOT set up vc.lib, so you cannot use most standard C functions (string and ctype functions are OK, but I/O and memory functions are not). The command line is passed as a single string, not parsed into argc/argv. You must open all Amiga libraries yourself.
Example:
`c
include <proto/exec.h>
include <proto/dos.h>
struct DosLibrary *DOSBase;
int main()
{
if (DOSBase = (struct DosLibrary *)OpenLibrary("dos.library", 0)) {
Write(Output(), "Hello, world!\n", 14);
CloseLibrary((struct Library *)DOSBase);
}
return 0;
}
`
`bash
vc -nostdlib -sc -sd -resident mycommand.c -o mycommand
`
2. Standard C Application with main(argc, argv)
Use Case: Standard C applications using main() with command line arguments and full stdio support.
Startup Code: startup.o (default)
Entry Point: main(int argc, char argv)
Compiler Options:
- -resident (for residentable executables)
Static Libraries:
- vlibos3:vc.lib (VBCC C library)
- vlibos3:amiga.lib (Amiga library)
- vlibos3:auto.lib (auto library opening)
- vlibos3:mieee.lib (math library if needed)
Why Use This: Standard configuration with full vc.lib support, command line parsing, and C library functionality. The startup code automatically opens required Amiga libraries and sets up the C runtime environment.
Example:
`bash
vc -resident myapp.c -o myapp
`
3. Heavyweight Unix/POSIX/Linux Command Port
Use Case: Ports of Unix/POSIX/Linux commands requiring extensive standard library support.
Startup Code: startup.o (default)
Entry Point: main(int argc, char argv)
Compiler Options:
- -resident (for residentable executables)
- -sd (small data model, default)
Static Libraries:
- vlibos3:vc.lib (VBCC C library)
- vlibos3:amiga.lib (Amiga library)
- vlibos3:auto.lib (auto library opening)
- vlibos3:mieee.lib (math library)
- Additional POSIX libraries as needed
Why Use This: Full-featured configuration for complex applications that need all standard library features, proper argument parsing, and extensive POSIX compatibility.
Example:
`bash
vc -resident myunixport.c -o myunixport
`
4. Resident Program (Shared Memory)
Use Case: Programs that need to stay resident in memory and be restarted without reloading from disk.
Startup Code: minres.o (minimal resident startup)
Entry Point: main(char *command) or main(void)
Compiler Options:
- -nostdlib (for minimal linking)
- -sc -sd (small code, small data - REQUIRED for resident programs)
- -resident (for residentable executables)
Static Libraries:
- vlibos3:amiga.lib (Amiga library only - no vc.lib)
Why Use This: For creating "pure" resident programs that can be kept in RAM and restarted without reloading. You must compile with small data model (-sd) and avoid absolute references to small data symbols. The program must be loaded with the AmigaDOS resident command and have the Pure flag set in file attributes.
Example:
`bash
vc -nostdlib -sc -sd -resident myresident.c -o myresident
`
Startup Code Features
- Multiple startup options: VBCC provides different startup modules for different use cases:
- startup.o: Standard startup with full vc.lib support and command line parsing
- minstartup.o: Minimal startup without vc.lib setup or command line parsing
- minres.o: Minimal startup for resident programs (shared memory)
- Automatic library opening/closing: auto.lib can open/close required Amiga libraries automatically
- Stack setup: Initializes stack and stack pointer
- BSS clearing: Zeroes uninitialized data segments
- Constructor/destructor calls: Calls C++ constructors/destructors if present
- Environment setup: Sets up environment variables and arguments
- Signal handling: Initializes signal handlers
- Floating point: Sets up floating point environment (if needed)
- AmigaOS integration: Handles AmigaOS-specific process and library setup
- Entry point flexibility: VBCC provides different entry point signatures:
- main(int argc, char argv): Standard C entry point with parsed arguments (startup.o)
- main(char *command): Single string command line (minstartup.o, minres.o)
- main(void): No command line arguments (minstartup.o, minres.o)
VBCC-Specific Pragmas and Attributes
| Pragma/Attribute | Description |
|---|---|
| `#pragma printflike` | Mark function as printf-like for format checking/optimization |
| `#pragma scanflike` | Mark function as scanf-like for format checking/optimization |
| `#pragma only-inline` | Only allow inlining for following functions |
| `#pragma opt <n>` | Set optimization options for following functions |
| `#pragma pack(n)` | Set structure member alignment |
| `#pragma pack(push[,n])` | Push current structure alignment, optionally set new alignment |
| `#pragma pack(pop)` | Pop structure alignment stack |
| `__interrupt` | Mark function as interrupt handler (target-specific) |
| `__section("name")` | Place function/object in named section (target-specific) |
| `__far`, `__near`, `__huge` | Memory model/pointer attributes (target-specific) |
| `__noinline` | Prevent function from being inlined |
| `__entry` | Mark function/object to be preserved even if unused |
| `__regsused("list")` | Specify volatile registers used by a function |
| `__varsmodified("list")` | Specify external variables modified by a function |
| `__varsused("list")` | Specify external variables read by a function |
| `__writesmem(type)` | Specify function writes to memory of given type |
| `__typeof`, `__alignof`, `__offsetof` | Built-in type/offset/align operators |
Amiga-Specific Libraries and Features
| Library | Description | Features |
|---|---|---|
| `amiga.lib` | AmigaOS system integration library | System calls, process setup, utility funcs |
| `auto.lib` | Auto-open/close Amiga libraries | Automatic library management |
| `reaction.lib` | Reaction GUI support (if present) | GUI integration for AmigaOS |
Non-Standard Macros, Types, and System Integration
| Macro/Type/Feature | Description |
|---|---|
| `__AMIGA__` | Defined when compiling for Amiga targets |
| `__VBCC__` | Defined for all VBCC compilations |
| `__M68K__`, `__PPC__` | Defined for target CPU |
| `__vc_inline` | Inline function specifier (VBCC-specific) |
| `va_start`, `va_end`, `va_arg` | Custom stdarg.h implementation (target-specific) |
| `startup.o`/`minstartup.o`/`resident.o` | Startup object files for Amiga targets |
| `vclib` | Standard C library for VBCC |
| `NDK`/`vincludeos3:` | Amiga NDK and include path conventions |
Notable Amiga/VBCC Differences
- AmigaOS programs require special startup code and library management (not standard in ISO C)
- Some C99/C11 features are not available or only partially supported
- Many attributes and pragmas are target-specific (see backend docs)
- AmigaOS integration is handled via amiga.lib/auto.lib, not present in other C environments
- Resident/minimal startup options for small or memory-resident programs
Summary
VBCC provides a range of proprietary and Amiga-specific features for system integration, startup code, memory models, and function attributes, making it a powerful tool for Amiga and embedded development. Consult the backend and Amiga target documentation for further details on available attributes and system integration options.