Migrating to GoAhead 3/4

GoAhead 3 is a major upgrade from GoAhead 2. It incorporates new features and upgrades to existing capabilities. It also changes many APIs and interfaces. GoAhead 4 is a evolutionary upgrade to GoAhead 3 and is highly compatible with GoAhead 3.

Compatibility with GoAhead 3/4

We make every effort to preserve compatibility, but with GoAhead 3, we needed to make some important improvements that necessitated breaking compatibility with GoAhead 2. Rather than make several ongoing compatibility breaks we decided to make all the changes in one release. In this way we can ensure that GoAhead 3 quickly becomes a stable platform going forward and that GoAhead 4 is highly compatible with GoAhead 3. Please see our Compatibility Policy.

Legacy Support

To aid migrating existing GoAhead 2.X applications, GoAhead 3.X can be built to support the old GoAhead 2.X APIs. This is called legacy mode. In this mode, the old APIs are mapped to new APIs via compiler defines and shim APIs. For full details of the API mappings, see the ME_GOAHEAD_LEGACY section in src/goahead.h.

GoAhead 3.X is built by default without legacy mode. You can enable legacy mode by configuring via:

configure --set goahead.legacy=true
or if building via make:

This will enable the legacy APIs and type names. However, You are strongly encouraged to fully migrate your application to the GoAhead 3/4 APIs and to transition off the old GoAhead 2 APIs. Note: GoAhead 2 is now officially "end-of-life".

Changes in GoAhead 3/4

GoAhead 3 and 4 provide equivalent or greater functionality to that in GoAhead 2. While GoAhead 3 may have a different interface or API, the capabilities of GoAhead 2 have been continued in GoAhead 3, and in many cases, the features have been enhanced.

New Capabilities

The following new capabilities have been added to GoAhead 3 for which there is no equivalent in GoAhead 2. These additions should not require adjustment for applications developed under GoAhead 2.

Changed Capabilities

The following capabilities have been changed and may impact your GoAhead 3 applications.

Changed APIs

The internal APIs in GoAhead 3/4 have been upgraded. Some have been renamed and others modified. GoAhead 3/4 APIs have been renamed/converted on a function by function basis to equivalent APIs in GoAhead 2. Often, the APIs have very similar names to the previous counterpart.

Here is a partial list of changed APIs in GoAhead 3.X and 4.X:

For a complete list, see the ME_GOAHEAD_LEGACY section at the end of goahead.h for a list of all the API name mappings. It is strongly recommended that you refactor your application to use the new API naming.


GoAhead 3/4 uses a flexible URI routing mechanism to direct client requests to the appropriate handler. In GoAhead 2, this was done by hard-coded handlers. The routing framework is controlled by the route.txt configuration file. The routing framework has more flexibility and allows URI parsing and routing.

See Request Routing for more details.

© Embedthis Software. All rights reserved.