more wip

docs/en/en.json

@@ -423,6 +423,18 @@
                         "path": "/manuals/extensions",
                         "name": "Native extensions"
                     },
+                    {
+                        "path": "/manuals/extensions_details",
+                        "name": "Native extensions - Details"
+                    },
+                    {
+                        "path": "/manuals/extensions_best_practices",
+                        "name": "Native extensions - Best Practices"
+                    },
+                    {
+                        "path": "/manuals/extensions_build_variants",
+                        "name": "Native extensions - Build Variants"
+                    },
                     {
                         "path": "/manuals/iap",
                         "name": "In-app purchases"

docs/en/manuals/extensions.md

@@ -47,6 +47,7 @@ Let's build a very simple extension. First, we create a new root folder *myexten
 ![Manifest](images/extensions/manifest.png)
 
 ```yaml
+# C++ symbol in your extension
 name: "MyExtension"
 ```
 
@@ -152,6 +153,8 @@ dmExtension::Result FinalizeMyExtension(dmExtension::Params* params)
 //
 // DM_DECLARE_EXTENSION(symbol, name, app_init, app_final, init, update, on_event, final)
 
+// MyExtension is the C++ symbol that holds all relevant extension data.
+// It must match the name field in the `ext.manifest`
 DM_DECLARE_EXTENSION(MyExtension, LIB_NAME, AppInitializeMyExtension, AppFinalizeMyExtension, InitializeMyExtension, 0, 0, FinalizeMyExtension)
 ```
 

docs/en/manuals/extensions_best_practices.md

@@ -0,0 +1,46 @@
+# Best Practices
+
+Writing cross platform code can be difficult, but there are some ways to make it easier to both develop and maintain.
+Here we list some ways we at Defold work with cross platform native code and API's.
+
+## C++ code
+
+### Standard Template Libraries - STL
+
+Since the Defold engine doesn't use any STL code, except for some algorithms and math (std::sort, std::upper_bound etc), it may work for you to use STL in your extension.
+
+Again, bear in mind that ABI incompatibilites may hinder you when using your extension in conjunction with other extensions or 3rd party libraries.
+
+#### Strings
+
+In the Defold engine, we use `const char*` instead of `std::string`. And writing your own dynamic array or hash table isn't very hard, but there are also good alternatives found online.
+
+
+
+### Make functions hidden
+
+Use the `static` keywork on functions local to your compile unit if possible. This lets the compiler do some optimizations, and
+can both improve performance as well as reduce executable size.
+
+
+# 3rd party libraries
+
+When choosing a 3rd party library to use (regardless of language), we consider at least these things:
+
+* Functionality - Does it solve the particular problem you have?
+* Performance - Does it infer a performance cost in the runtime? For each frame, or
+* Library size - How much bigger will the final executable be? Is it acceptable
+* Dependencies - Does it require extra libraries
+* Support - What state is the library in? Does it have many open issues? Is it still maintained? etc...
+* License - Is it ok to use for this project?
+
+
+# Open source dependencies
+
+Always make sure that you have access to your dependencies.
+E.g. if you depend on something on github, there's nothing preventing that repository either being removed, or suddenly changes
+direction or ownership.
+
+The code in that library will be injected into your game, so make sure the library does what it's supposed to do, and nothing more!
+
+<legal note?>

docs/en/manuals/extensions_build_variants.md

@@ -0,0 +1,52 @@
+# Native Extensions - Build Variants
+
+## Build Variants
+
+When you bundle a game, you need to choose what type of engine you wish to use.
+
+  * Debug
+  * Release
+  * Headless
+
+These different versions are also referred to as `Build variants`
+
+Note: When you choose `Build and run` you'll get the debug version.
+
+### Debug
+
+This type of executable still has the debugging feature left inside it, such as:
+profiling, logging and hot reload.
+
+This variant is chosen during development of the game.
+
+### Release
+
+This variant has the debugging features disabled.
+This options is chosen when the game is ready to be released to the app store.
+
+### Headless
+
+This executable runs without any graphics. It means that you can run the game unit/smoke tests on a CI server,
+or even have it as a game server in the cloud.
+
+## App Manifest
+
+Not only can you add native code to the engine with the Native Extensions feature, you can also remove standard parts of the engine.
+E.g. if you don't need a physics engine, you can remove that from the executable.
+
+We support this via a file called an `App Manifest` (.appmanifest).
+In such a file, you can configure what libraries or symbols to remove, or perhaps add compile flags
+
+This feature is still in the works, and needs more attention.
+
+### Editing
+
+Currently, the process can be done manually, but we recommend our users to use the [Manifestation](https://britzl.github.io/manifestation/) tool
+to create their app manifest.
+
+Eventually, the creation and modification of the app manifests will be done in the Editor.
+
+### Syntax
+
+...
+

docs/en/manuals/extensions_details.md

@@ -4,15 +4,7 @@
 Here we list some relevant build information, in order to make the integrations with your extensions as easy as possible.
 
 Here are some things to consider when you create an extension for the Defold engine.
-
-# Static linkage
-
-The custom engine is built using static linkage.
-The main reason is that on iOS, multiple executable binaries in an .ipa aren't allowed in the app store.
-
-# No Exceptions:
-
-We don't make use of any exceptions in the engine, as it decreases executable size and improves the runtime performance. This may be beneficial for you to if you wish to get a minimal extension.
+For more general guidelines on how to develop cross platform native code, and also extension/Lua apis, please refer to [Native Extensions - Best Practices](/manuals/extensions_best_practices)
 
 # C++ version
 
@@ -20,60 +12,46 @@ In the engine itself we use no C++ version higher than C++98. While you may use
 
 When creating libraries (such as extensions), it's good to keep the lowest common denominator as a target.
 
-# Standard Template Libraries - STL
-
-Since the Defold engine doesn't use any STL code (except std::sort), it may work for you to use STL in your extension. Again, bear in mind that ABI incompatibilites may hinder you when using your extension in conjunction with other extensions.
-
-In the Defold engine, we use `const char*` instead of `std::string`. And writing your own dynamic array or hash table isn't very hard, but there are also good alternatives found online.
-
 # Toolchain
 
-Clang - MscOS, iOS, (Win32)
+Clang - macOS, iOS, Win32
 GCC - Android, Linux (deprecated)
-CL - Windows (deprecated)
-
-_NOTE: We are aiming to compile all platforms with Clang in the near future in order to streamline our builds_
 
 ## SDK Versions
 
-* Android:
+* Android: NDK 10e, Build Tools 23.0.2, Api Level 14
 * iOS: iPhoneOS11.2.sdk
 * MacOS: MacOSX10.13.sdk
 * Windows: WindowsKits 8.1 + 10.0, Microsoft Visual Studio 14.0
 * Linux: Ubuntu 16.04, gcc 5.4.0, libssl-dev, uuid-dev, libxi-dev, libopenal-dev, libgl1-mesa-dev, libglw1-mesa-dev, freeglut3-dev
-* Html5: Emscripten 1.35.0,
+* Html5: Emscripten 1.38.0,
 
 ## C++ version + ABI compatibility
 
-We build our engine using `-std=c++98`
-
-For iOS/MacOS, we use `-miphoneos-version-min=6.0` and `-mmacosx-version-min=10.7` respectively.
-
 * Linux: `GCC 5.4.0`
 * Android:`GCC 4.8`
 * Html5: `Emscripten 1.35.0`
 * Win32: `Microsoft Visual Studio 14.0` alt `clang-6.0`
 * iOS/MacOS: `apple-clang` alt `clang-6.0`
 
-# Win32 + Clang
-
-A recent addition is to be able to build the Windows builds using clang.
-This allows for faster builds on our servers, and also it allows us to streamline our builds.
-
-_NOTE: This feature is new, so it's not enabled by default yet_
-
-You can use this feature by adding the flag `use-clang` to your app manifest:
+For iOS/MacOS, we use `-miphoneos-version-min=6.0` and `-mmacosx-version-min=10.7` respectively.
 
-    platforms:
-        x86_64-win32:
-            use-clang: true
+We don't specify a specific C++ version, so we use the default of each compiler.
 
+# Win32 + Clang
 
-## CL.exe / LINK.exe
+A recent addition is to be able to build the Windows builds using clang.
+This allows for faster builds on our servers, and also allows us to streamline our builds.
 
-Although this feature is still supported, it will soon be deprecated.
+# Static linkage
 
+The custom engine is built using static linkage.
+The main reason is that on iOS version < 8, multiple executable binaries in an .ipa aren't allowed in the app store.
 
+# No C++ Exceptions
 
+We don't make use of any exceptions in the engine.
+It isn't generally used in game engines, since the data is (mostly) known beforehand, during development.
+Removing the support for C++ exceptions decreases executable size and improves the runtime performance.