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..f3fc96292b --- /dev/null +++ b/subprojects/platform-native/src/docs/guide-templates/building-native-application/README.adoc @@ -0,0 +1,162 @@ += 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. + + +== 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. + +[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 the tests, if any. +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, typically .o and .obj, are built here +<3> The `tmp` folder is a temporary directory for all Gradle tasks. +You can find `options.txt` file containing all flags for both compile and link tasks. + +NOTE: To learn more about dependencies on other projects not covered, have a look at the transitive dependency sample for a demonstration. + +NOTE: Nokee integrates with several IDEs (Integrated Development Environments): [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 +// Maybe: To further explore (Nokee metaverse and the NFTs) +// NFT -> Nokee Fruit Tomato + +//TODO a downloadable example with more complex application code + +// 2 button at top like other pages + + +== Guides and Customization?? + +To learn more on how to further customize {C application} projects, check out the user manual chapter on link:TODO[Building native projects]. + +You also May Be Interested in other guides and samples around common configuration: + +TODO: Link to other guides and samples…