Building native application guides

subprojects/platform-native/src/docs/guide-templates/building-native-application/README.adoc

@@ -0,0 +1,172 @@
+= Building {C Applications}
+:summary: Building {C application}s.
+:type: guide-chapter
+:tags: guide, {application}, sources, native, {C}, gradle
+:category: {C}
+:description: Learn how to build {an application} implemented in {C} using the Gradle Nokee plugins.
+
+This guide demonstrates how to create a {C application} using the Nokee plugins for Gradle.
+You can follow the guide step-by-step to create a new project from scratch or download the complete project using the links above.
+//TODO ADD LINK to complete project
+
+
+== Before starting, you will need to have
+
+* A text editor or IDE - for example https://www.jetbrains.com/idea/download/[IntelliJ IDEA]
+* A Java Development Kit (JDK), version 8 or higher - for example https://adoptopenjdk.net/[AdoptOpenJDK]
+* The latest https://gradle.org/install[Gradle distribution]
+* An installed C compiler.
+See which link:TODO[C toolchains] are supported by Nokee.
+
+== 1. Create a project folder
+
+Create in your project folder a new folder for your project and a new empty setting files named 'settings.gradle')
+
+
+This will mark* the root of your project in Gradle.
+//TODO might want to use Indicates were the root of your project "starts" in gradle.- I'm not sure what this really set/accomplishes
+[source,terminal]
+----
+$ mkdir demo           //  <1>
+$ cd demo              //  <2>
+$ touch settings.gradle//  <3>
+----
+<1> Creates Directory named "demo"
+<2> Changes Directory to "demo"
+<3> Creates an empty Gradle setting(workspace) buildscript
+// TODO setting workspace to review terminology maybe add link to setting.gradle
+
+
+
+== 2. Add {C application} capability to the project
+
+Create the project buildscript, e.g. `build.gradle`.
+
+Edit `build.gradle` and add the following :
+
+[source,groovy]
+----
+plugins {                            // <1>
+	id 'dev.nokee.c-application' // <2>
+}
+----
+
+<1> Using the plugin block to apply plugins that extends the project capability.
+You can apply any Gradle project plugin here.
+Learn more about the link:TODO[plugins block in Gradle's documentation].
+Refer to each plugin's reference chapter to learn more about each individual plugins.
+
+<2> Apply Nokee's {C application} plugin.
+Learn more about link:TODO[this plugin at its reference chapter].
+
+NOTE: Gradle support two domain specific language (DSL): Groovy DSL and Kotlin DSL.
+For this guide, we will use Groovy DSL which is closer in syntax to {C} language.
+Learn more about Gradle DSL language in the link:TODO[Getting started chapter].
+
+== 3. Add {C} code
+
+By default, Nokee uses a default link:TODO[Gradle's conventional source layout].
+All {C} application code is located at `src/main/c` with private headers located at `src/main/headers`.
+
+Add a "hello world" to your application:
+
+.src/main/c/main.c
+[source,c]
+----
+#include <stdio>
+#include <my_string.h>
+
+int main(int argc, char** argv) {
+	printf("%s\n", kHelloWorld);
+	return 0;
+}
+----
+
+.src/main/headers/my_string.h
+[source,c]
+----
+static const char* kHelloWorld = "Hello, World!";
+----
+
+
+== 4. Build the {application}
+Build using gradle:
+[source,terminal]
+----
+$ gradle build                  // <1>
+
+BUILD SUCCESSFUL                // <2>
+7 actionable tasks: 7 executed  // <3>
+----
+<1> Invoke the task with gradle , in this case *build*
+<2> Status of build which is successful
+<3> Summary of total tasks completed and their dependencies
+
+
+
+The build task compiles the {C} sources, links the object files and runs tests.
+The following shows the content of the `build` folder:
+
+[source,terminal]
+----
+$ tree ./build
+./build
+|- exe
+  |- main
+    |- app // <1>
+|- objs  // <2>
+  |- main
+    |- <hash>
+      |- main.o
+|- tmp // <3>
+  |- compileC
+    |- options.txt
+  |- link
+    |- options.txt
+----
+<1> The built executable
+<2> All object files builds and stores here.
+<3> The `tmp` folder is a temporary workspace for all Gradle tasks.
+The file `options.txt` contains all flags for both compile and link tasks.
+
+
+NOTE: Nokee integrates with several IDEs: [Visual Studio], [Xcode] and [Clion].To learn more, have a look at their respective linked documentation to configure those IDEs integration in your project.
+
+== 5. Run the application
+
+Look inside the `build` folder, and you will notice the appearance of an exe folder.
+By convention, Gradle will place all {applications} in subfolders named according to the component name.
+In this case, you will find your assembled executable in `build/exe/main` and it will be called `app` (or `app.exe` under Windows).
+
+Now run your newly built executable.
+
+[source,terminal]
+----
+$ ./build/exe/main/app
+Hello, World!
+----
+== 6. Test and explore different possibilities & summaries
+Here is an example and link to download this demo application for you to test out:
+link:TODO[Complete_Example]
+//TODO a downloadable example with more complex application code
+[source,terminal]
+----
+----
+//TODO add box with demo of the app with both toggles like other pages
+
+== 7. Customization and Other helpful Guides
+
+
+How to further customize {C application} projects, check out the user manual chapter on link:TODO[Building native projects].
+
+How to integrate Nokee with  link:TODO[Visual Studio], link:TODO[Xcode] and link:TODO[Clion] IDEs.
+
+How to set different dependencies, check out a demonstration link:TODO[Transitive dependency sample].
+//The link:TODO[Transitive dependency sample] covers how to set dependencies on other project.
+//TODO add link to "transitive dependency sample"
+
+More guides and samples around common configuration:
+
+link:TODO[Nokee application Plugins], link:TODO[Getting started with Gradle]
+
+//TODO: Link to other guides and samples…