More info about recommended project layout

docs/en/manuals/extensions_best_practices.md

@@ -3,7 +3,20 @@
 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
+## Defold code
+
+In the Defold engine we use C++ very sparingly. In fact, most code is very C-like.
+We avoid templates, except for a few container classes, due to the fact that templates both incurs a cost on compilation times
+as well as executable size.
+
+### C++ version
+
+The defold source it built with the default C++ version of each compiler (See [Native Extensions - Best Practices](/manuals/extensions_best_practices#_)).
+
+We avoid using the latest features or versions of C++. Mostly because we already have what we need to build an game engine.
+Keeping track of the latest features of C++ is a time consuming task, and to really master those features will require a lot of precious time.
+
+It also has the added benefit for our extension developers that we keep a stable ABI.
 
 ### Standard Template Libraries - STL
 
@@ -11,18 +24,20 @@ Since the Defold engine doesn't use any STL code, except for some algorithms and
 
 Again, bear in mind that ABI incompatibilites may hinder you when using your extension in conjunction with other extensions or 3rd party libraries.
 
-#### Strings
+Avoiding the (heavily tepmlated) STL libraries, also improves on our build times, and more importantly, the executable size.
 
-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.
+#### Strings
 
+In the Defold engine, we use `const char*` instead of `std::string`.
 
+`std::string` is a common pitfall when mixing different versions of C++ or compiler versions: you'll get an ABI mismatch.
+For us, it's better to use `const char*` and a few helper functions.
 
 ### 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:
@@ -44,3 +59,73 @@ 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?>
+
+
+# Project structure
+
+When creating an extension, there are a few things that help out in developing it as well as maintaining it.
+
+## Lua api
+
+There should only be one Lua api, and one implementation of it.
+This makes it a lot easier to behave the same for all platforms.
+
+If the platform in question shouldn't support the extension, we recommend simply not registering a Lua module at all.
+That way you can detect support by checking for nil:
+
+    if myextension ~= nil then
+        myextension.do_something()
+    end
+
+## Folder structure
+
+Here is a folder structure that we use frequently for our extensions.
+
+    /root
+        /input
+        /main                            -- All the files for the actual example project
+            /...
+        /myextension                     -- The actual root folder of the extension
+            ext.manifest
+            /include                     -- External includes, used by other extensions
+            /libs
+                /<platform>              -- External libraries for all supported platforms
+            /src
+                myextension.cpp          -- The extension Lua api and the extension life cycle functions
+                                            Also contains generic implementations of your Lua api functions.
+                myextension_private.h    -- Your internal api that each platform will implement (I.e. `myextension_Init` etc)
+                myextension.mm           -- If native calls are needed for iOS/macOS. Implements `myextension_Init` etc for iOS/macOS
+                myextension_android.cpp  -- If JNI calls are needed for Android. Implements `myextension_Init` etc for Android
+                /java
+                    /<platform>          -- Any java files needed for Android
+            /res                         -- Any resources needed for a platform
+            /external
+                README.md                -- Notes/scripts on how to build or package any external libraries
+        /bundleres                       -- Resources that should be bundles for (see game.project and the [bundle_resources setting]([physics scale setting](/manuals/project-settings/#_project))
+            /<platform>
+        game.project
+        game.appmanifest                 -- Any extra app configuration info
+
+
+Note that the `myextension.mm` and `myextension_android.cpp` are only needed if you are doing specific native calls for that platform.
+
+### Platform folders
+
+In certain places, we use the platform architecture as a folder name, to know what files to use when compiling/bundling the application.
+These are of the form:
+
+    <architecture>-<platform>
+
+The current list is:
+
+    arm64-ios,armv7-ios,arm64-android,armv7-android,x86_64-linux,x86_64-osx,x86_64-win32,x86-win32
+
+So for instance, put platform specific libraries under:
+
+    /libs
+        /arm64-ios
+                            /libFoo.a
+        /arm64-android
+                            /libFoo.a
+
+

docs/en/manuals/extensions_build_variants.md

@@ -39,6 +39,22 @@ In such a file, you can configure what libraries or symbols to remove, or perhap
 
 This feature is still in the works, and needs more attention.
 
+### Combined context
+
+The app manifest actually has the same structure and syntax as the extension manifest.
+This allows us to merge the contexts for one platform together when finally building.
+
+And, Defold itself, has its own build manifest as the foundation (`build.yml`).
+For each extension that is built, the manifests are combined as follows:
+
+	manifest = merge(game.appmanifest, ext.manifest, build.yml)
+
+This is so the user can override the default behaviour of the engine and also each extension.
+
+And, for the final link stage, we merge the app manifest with the defold manifest:
+
+	manifest = merge(game.appmanifest, build.yml)
+
 ### Editing
 
 Currently, the process can be done manually, but we recommend our users to use the [Manifestation](https://britzl.github.io/manifestation/) tool
@@ -48,5 +64,110 @@ Eventually, the creation and modification of the app manifests will be done in t
 
 ### Syntax
 
-...
-
+Here is an exampple from the [Manifestation](https://britzl.github.io/manifestation/) tool for reference.
+(Subject to change. Don't copy this file directly. Instead, use the online tool)
+
+	platforms:
+	    x86_64-osx:
+	        context:
+	            excludeLibs: []
+	            excludeSymbols: []
+	            libs: []
+	            linkFlags: []
+	    x86_64-linux:
+	        context:
+	            excludeLibs: []
+	            excludeSymbols: []
+	            libs: []
+	            linkFlags: []
+	    js-web:
+	        context:
+	            excludeLibs: []
+	            excludeJsLibs: []
+	            excludeSymbols: []
+	            libs: []
+	            linkFlags: []
+	    wasm-web:
+	        context:
+	            excludeLibs: []
+	            excludeJsLibs: []
+	            excludeSymbols: []
+	            libs: []
+	            linkFlags: []
+	    x86-win32:
+	        context:
+	            excludeLibs: []
+	            excludeSymbols: []
+	            libs: []
+	            linkFlags: []
+	    x86_64-win32:
+	        context:
+	            excludeLibs: []
+	            excludeSymbols: []
+	            libs: []
+	            linkFlags: []
+	    armv7-android:
+	        context:
+	            excludeLibs: []
+	            excludeJars: []
+	            excludeSymbols: []
+	            libs: []
+	            linkFlags: []
+	    armv7-ios:
+	        context:
+	            excludeLibs: []
+	            excludeSymbols: []
+	            libs: []
+	            linkFlags: []
+	    arm64-ios:
+	        context:
+	            excludeLibs: []
+	            excludeSymbols: []
+	            libs: []
+	            linkFlags: []
+
+
+#### White listing
+
+For all the keywords, we apply white listing filter.
+This is to avoid illegal path handling and accessing files outside of the build upload folder.
+
+#### linkFlags
+
+Here you can add flags to the specific platform compiler.
+
+#### libs
+
+This flag is only used if you wish to add a library that is part of the platform or Defold SDK.
+All libraries in your app's extensions are added automatically, and you shouldn't add those to this flag.
+
+Here's an example where the 3D physics is removed from the engine:
+
+    x86_64-linux:
+        context:
+            excludeLibs: ["physics","LinearMath","BulletDynamics","BulletCollision"]
+            excludeSymbols: []
+            libs: ["physics_2d"]
+            linkFlags: []
+
+#### Exclude flags
+
+These flags are used to remove things previously defined in the platform context.
+
+Here's an example of how to remove the Facebook extensiokn from the engine.
+Note the `(.*)` which is a regexp to help remove the correct items.
+
+    armv7-android:
+        context:
+            excludeLibs: ["facebookext"]
+            excludeJars: ["(.*)/facebooksdk.jar","(.*)/facebook_android.jar"]
+            excludeSymbols: ["FacebookExt"]
+            libs: []
+            linkFlags: []
+
+#### Where's the list of all flags, libraries, symbols???
+
+We might put some of them here, but we also think our time is better spent
+completing the feature of moving the manifest configuration into the Editor, making it a seamless step for the user.
+
+In the meantime, we'll keep the [Manifestation](https://britzl.github.io/manifestation/) tool updated.

docs/en/manuals/extensions_details.md

@@ -15,7 +15,9 @@ When creating libraries (such as extensions), it's good to keep the lowest commo
 # Toolchain
 
 Clang - macOS, iOS, Win32
-GCC - Android, Linux (deprecated)
+GCC - Android, Linux
+
+*We're plan make both Android and Linux to use Clang as well*
 
 ## SDK Versions
 
@@ -54,4 +56,11 @@ 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.
 
+# Defold SDK
+
+With each (biweekly) release of Defold, we release a new Defold SDK.
+With it, we ship the libraries of the engine, and also a build manifest file,
+which is identical in structure and syntax as the [extension](/manuals/extensions_build_variants) and [app](/manuals/extensions_build_variants) manifests.
+
+(This sdk is not yet public)
 

docs/ko/manuals/project-settings.md

@@ -55,7 +55,7 @@ $ adb shell cat /mnt/sdcard/Android/data/com.defold.dmengine/files/log.txt
 이 프로젝트가 사용하는 프로젝트의 **Library URL:s** ([Defold dashboard](https://www.defold.com/dashboard/)에서 찾을 수 있음) 을 쉼표로 구분하여 나열합니다. 종속 프로젝트의 멤버여야 합니다.
 #### custom_resources (hidden setting)
 프로젝트에 포함될 쉼표로 구분된 리소스 목록입니다. 디렉토리가 지정되면 이 디렉토리의 모든 파일과 디렉토리들이 재귀적으로(recursively) 포함됩니다.
-#### bundle_resources (hidden setting)
+#### bundle_resources
 번들을 만들 때 결과 패키지에 그대로 복사해야하는 리소스 파일과 폴더를 포함하고 있는 디렉토리입니다. 이 디렉토리는 예를 들어 "/res" 같이 프로젝트 루트의 절대 경로(absolute path)로 지정됩니다. 이 리소스 디렉토리에는 platform 이나 architecure-platform 이라는 이름의 하위 폴더를 포함해야 합니다. 지원되는 플랫폼은 ios, android, osx 입니다. 지원되는 arc-platform 계열으로는 armv7-ios, arm64-ios, armv7-android, x86_64-osx 가 있습니다. 또한 common 이라는 이름의 하위 폴더에 모든 플랫폼의 공통적인 리소스 파일을 포함 시킬 수도 있습니다.
 
 ## Display