From 2b584b99f042b6a18b9fb22712b8b0183a535dbe Mon Sep 17 00:00:00 2001 From: Daniel Lacasse Date: Fri, 14 Jan 2022 12:11:06 -0500 Subject: [PATCH 1/5] Draft guide for building native application with Nokee --- .../building-native-application/README.adoc | 172 ++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 subprojects/platform-native/src/docs/guide-templates/building-native-application/README.adoc 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..e363155ffc --- /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. + +== What we'll build + +We’ll generate a {C application} that follows Nokee and Gradle’s conventions. + +== What we’ll need + +* 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 + +First, let's create an empty folder for our project and use the build-in `wrapper` task to create a Gradle wrapper script, e.g. `gradlew`. + +[source,terminal] +---- +$ mkdir demo +$ cd demo +$ gradle wrapper + +BUILD SUCCESSFUL +1 actionable tasks: 1 executed +$ tree . +├── gradle // <1> +│ └── wrapper +│ ├── gradle-wrapper.jar +│ └── gradle-wrapper.properties +├── gradlew // <2> +└── gradlew.bat // <2> + +2 directories, 4 files +$ touch settings.gradle // <3> + +---- + +<1> Generated folder for wrapper files + +<2> Gradle wrapper start scripts + +<3> Create an empty Gradle workspace buildscript + +We now have a Gradle project setup. +Let's configure {C application} capability to the project. + +== 2. Configure {C application} capability + +First, create the project buildscript, e.g. `build.gradle`. + +build.gradle + +[source,groovy] +---- +plugins { // <1> + id 'dev.nokee.c-application' // <2> +} +---- + +<1> We use the plugin block to apply plugins that extends the project capability. +We 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> We 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 link:TODO[Gradle's conventional source layout]. +All {C} application code is located at `src/main/c` and its private headers are located at `src/main/headers`. + +Let's add a very simple hello world: + +.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!"; +---- + +Next, let's build the application. + +== 3. Build the {application} + +[source,terminal] +---- +$ ./gradlew build + +BUILD SUCCESSFUL +7 actionable tasks: 7 executed +---- + +NOTE: The first time you run the wrapper script, e.g. `gradlew[.bat]`, there may be a delay while that version of gradle is downloaded and stored locally in your `~/.gradle/wrapper/dists` folder. +Learn link:TODO[why Gradle download distribution when using wrapper]. + +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 are built here +<3> The `tmp` folder is a temporary workspace for all Gradle tasks. +You can find `options.txt` file containing all flags for both compile and link tasks. + +NOTE: Dependencies on other projects isn’t covered in this guide. +To learn more about this subject, have a look at the transitive dependency sample for a demonstration. + +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. + +== 4. 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! +---- + +== Next steps + +To learn more about how you can further customize {C application} projects, check out the user manual chapter on link:TODO[Building native projects]. +Check out other guides and samples around common configuration: + +TODO: Link to other guides and samples… From c58d7afec22e5cd066b2549476854386c31ba6f2 Mon Sep 17 00:00:00 2001 From: Daniel Lacasse Date: Thu, 20 Jan 2022 19:01:54 -0500 Subject: [PATCH 2/5] Remove any mention to Gradle wrapper The Gradle wrapper is unecessary to the understanding on how to build a native application. --- .../building-native-application/README.adoc | 29 +++---------------- 1 file changed, 4 insertions(+), 25 deletions(-) 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 index e363155ffc..7416abeb81 100644 --- 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 @@ -22,34 +22,16 @@ We’ll generate a {C application} that follows Nokee and Gradle’s conventions == 1. Create a project folder -First, let's create an empty folder for our project and use the build-in `wrapper` task to create a Gradle wrapper script, e.g. `gradlew`. +First, let's create an empty folder for our project and create an empty `settings.gradle` file while mark the root of your project in Gradle. [source,terminal] ---- $ mkdir demo $ cd demo -$ gradle wrapper - -BUILD SUCCESSFUL -1 actionable tasks: 1 executed -$ tree . -├── gradle // <1> -│ └── wrapper -│ ├── gradle-wrapper.jar -│ └── gradle-wrapper.properties -├── gradlew // <2> -└── gradlew.bat // <2> - -2 directories, 4 files -$ touch settings.gradle // <3> - +$ touch settings.gradle // <1> ---- -<1> Generated folder for wrapper files - -<2> Gradle wrapper start scripts - -<3> Create an empty Gradle workspace buildscript +<1> Create an empty Gradle workspace buildscript We now have a Gradle project setup. Let's configure {C application} capability to the project. @@ -110,15 +92,12 @@ Next, let's build the application. [source,terminal] ---- -$ ./gradlew build +$ gradle build BUILD SUCCESSFUL 7 actionable tasks: 7 executed ---- -NOTE: The first time you run the wrapper script, e.g. `gradlew[.bat]`, there may be a delay while that version of gradle is downloaded and stored locally in your `~/.gradle/wrapper/dists` folder. -Learn link:TODO[why Gradle download distribution when using wrapper]. - 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: From 70d34e8e4d318a76e2f2a80ef6bbcc060d994644 Mon Sep 17 00:00:00 2001 From: Ladalz Date: Tue, 10 May 2022 19:42:26 -0400 Subject: [PATCH 3/5] Reword C application guide --- .../building-native-application/README.adoc | 76 +++++++++++-------- 1 file changed, 44 insertions(+), 32 deletions(-) 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 index 7416abeb81..a0225e69ec 100644 --- 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 @@ -8,53 +8,54 @@ 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. -== What we'll build -We’ll generate a {C application} that follows Nokee and Gradle’s conventions. - -== What we’ll need +== 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. +See which link:TODO[C toolchains] are supported by Nokee. == 1. Create a project folder -First, let's create an empty folder for our project and create an empty `settings.gradle` file while mark the root of your project in Gradle. + 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 -$ cd demo -$ touch settings.gradle // <1> +$ 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 -<1> Create an empty Gradle workspace buildscript -We now have a Gradle project setup. -Let's configure {C application} capability to the project. -== 2. Configure {C application} capability +== 2. Add {C application} capability to the project -First, create the project buildscript, e.g. `build.gradle`. +Create the project buildscript, e.g. `build.gradle`. -build.gradle +Edit `build.gradle` and add the following : [source,groovy] ---- -plugins { // <1> +plugins { // <1> id 'dev.nokee.c-application' // <2> } ---- -<1> We use the plugin block to apply plugins that extends the project capability. -We can apply any Gradle project plugin here. +<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> We apply Nokee's {C application} plugin. +<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. @@ -63,10 +64,10 @@ Learn more about Gradle DSL language in the link:TODO[Getting started chapter]. == 3. Add {C} code -By default, Nokee uses link:TODO[Gradle's conventional source layout]. -All {C} application code is located at `src/main/c` and its private headers are located at `src/main/headers`. +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`. -Let's add a very simple hello world: +Add a "hello world" to your application: .src/main/c/main.c [source,c] @@ -86,17 +87,21 @@ int main(int argc, char** argv) { static const char* kHelloWorld = "Hello, World!"; ---- -Next, let's build the application. - -== 3. Build the {application} +== 4. Build the {application} +Build using gradle: [source,terminal] ---- -$ gradle build +$ gradle build // <1> -BUILD SUCCESSFUL -7 actionable tasks: 7 executed +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: @@ -129,7 +134,7 @@ To learn more about this subject, have a look at the transitive dependency sampl 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. -== 4. Run the application +== 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. @@ -142,10 +147,17 @@ Now run your newly built executable. $ ./build/exe/main/app Hello, World! ---- +== 6. Test and explore different possibilities & summaries + +//TODO a downloadable example with more complex application code + +// 2 button at top like other pages + + +== Guides and Customization?? -== Next steps +To learn more on how to further customize {C application} projects, check out the user manual chapter on link:TODO[Building native projects]. -To learn more about how you can further customize {C application} projects, check out the user manual chapter on link:TODO[Building native projects]. -Check out other guides and samples around common configuration: +You also May Be Interested in other guides and samples around common configuration: TODO: Link to other guides and samples… From 2dc3261c3c3c98f0a3599378aa3229d49cf2c839 Mon Sep 17 00:00:00 2001 From: Ladalz Date: Tue, 24 May 2022 22:55:51 -0400 Subject: [PATCH 4/5] WIP to discuss how to layout guides --- .../building-native-application/README.adoc | 37 +++++++++++-------- 1 file changed, 21 insertions(+), 16 deletions(-) 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 index a0225e69ec..fc2d9acd32 100644 --- 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 @@ -7,6 +7,7 @@ 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 @@ -19,11 +20,11 @@ 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') +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> @@ -97,13 +98,13 @@ $ gradle build // <1> BUILD SUCCESSFUL // <2> 7 actionable tasks: 7 executed // <3> ---- -<1> invoke the task with gradle , in this case build +<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 build task compiles the {C} sources, links the object files and runs tests. The following shows the content of the `build` folder: [source,terminal] @@ -124,15 +125,12 @@ $ tree ./build |- options.txt ---- <1> The built executable -<2> All object files are built here +<2> All object files builds and stores here. <3> The `tmp` folder is a temporary workspace for all Gradle tasks. -You can find `options.txt` file containing all flags for both compile and link tasks. +The file `options.txt` contains all flags for both compile and link tasks. -NOTE: Dependencies on other projects isn’t covered in this guide. -To learn more about this subject, have a look at the transitive dependency sample for a demonstration. -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. +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 @@ -148,16 +146,23 @@ $ ./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: //TODO a downloadable example with more complex application code +//TODO add box with demo of the app with both toggles like other pages + +== 7. Customization and Other helpful Guides + -// 2 button at top like other pages +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. -== Guides and Customization?? +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" -To learn more on how to further customize {C application} projects, check out the user manual chapter on link:TODO[Building native projects]. +More guides and samples around common configuration: -You also May Be Interested in other guides and samples around common configuration: +link:TODO[Nokee application Plugins], link:TODO[Getting started with Gradle] -TODO: Link to other guides and samples… +//TODO: Link to other guides and samples… From ea937cc7aba82b38e7c4dc04e41c42358ae95ccd Mon Sep 17 00:00:00 2001 From: Ladalz Date: Tue, 21 Jun 2022 13:22:23 -0400 Subject: [PATCH 5/5] adjust text and position for Link to be added --- .../guide-templates/building-native-application/README.adoc | 4 ++++ 1 file changed, 4 insertions(+) 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 index fc2d9acd32..de36a8d571 100644 --- 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 @@ -147,7 +147,11 @@ 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