diff --git a/subprojects/platform-native/src/docs/guide-templates/building-native-application/README.adoc b/subprojects/platform-native/src/docs/guide-templates/building-native-application/README.adoc new file mode 100644 index 0000000000..de36a8d571 --- /dev/null +++ b/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 +#include + +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 + |- + |- 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…