Add android platform support (#4)

attiasas · Sep 3, 2023 · c1ba42b · c1ba42b
1 parent 79462ff
commit c1ba42b
Show file tree

Hide file tree

Showing 34 changed files with 745 additions and 295 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,5 +1,5 @@
 - [ ] I read the [contribution](../CONTRIBUTING.md) notes.
 
-- [ ] All [tests](../CONTRIBUTING.md) passed. If this feature is not already covered by the tests, I added new
+- [ ] All [tests](https://github.com/attiasas/open-interactive-simulation-deployer/actions/workflows/test.yml) passed. If this feature is not already covered by the tests, I added new
   tests.
 -----
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,21 +6,22 @@
 
 # ⚒️ Building the plugin
 
-To build the library sources, please follow these steps:
-
-1. Clone the code from Git.
-2. Build the plugin by running the following Gradle command:
-    ```
-    gradlew clean build
-    ```
+Build the plugin by running the following Gradle command:
+```
+gradlew clean build
+```
 
-To build the library sources and publish it locally, run the following Gradle command:
+To build the plugin sources and publish it locally, run the following Gradle command:
 ```
-    gradlew publishToMavenLocal
+gradlew publishToMavenLocal
 ```
+After running the command you will be able to use the library from `mavenLocal()` in a test project.
 
 ---
 
 # 🧪 Testing the plugin
 
 To test the library sources, please follow these steps:
+```
+gradlew clean check
+```
diff --git a/README.md b/README.md
@@ -102,7 +102,7 @@ Download the installation bash [script](src/main/resources/installOIS.sh) and ru
 4. [Optional, Recommended] Add the core library dependency in your project `build.gradle`
    ```groovy
     dependencies {
-        implementation group: 'org.attias.open.interactive.simulation', name: 'open-interactive-simulation-core', version: '1.0-SNAPSHOT'
+        implementation group: 'org.attias.open.interactive.simulation', name: 'open-interactive-simulation-core', version: '0.1'
     }
    ```
 
@@ -114,17 +114,19 @@ a file known as `simulation.ois`. This file will contain all the essential proje
 
 The file follows a JSON format and comprises the subsequent attributes:
 
-| Attribute             | Description                                                                                           |
-|-----------------------|-------------------------------------------------------------------------------------------------------|
-| title                 | The designated title of your simulation project.                                                      |
-| initialState          | The state that will be activated upon initiating the simulation.                                      |
-| states                | A mapping of all implemented IState classes within your project, along with their corresponding keys. |
-| publish               | The configurations for publishing your OIS project and facilitating its distribution.                 |
-| publish.platforms     | The designated platforms on which the simulation will operate, with at least one platform defined.    |
-| publish.iconsDir      | [Optional] The directory housing all project icons.                                                   |
-| publish.publishedName | [Optional, Default is the project name] The name of the resulting artifacts upon publishing.          |
-
-For instance:
+| Attribute                    | Description                                                                                           |
+|------------------------------|-------------------------------------------------------------------------------------------------------|
+| title                        | The designated title of your simulation project.                                                      |
+| initialState                 | The state that will be activated upon initiating the simulation.                                      |
+| states                       | A mapping of all implemented IState classes within your project, along with their corresponding keys. |
+| publish                      | The configurations for publishing your OIS project and facilitating its distribution.                 |
+| publish.platforms            | The designated platforms on which the simulation will operate, with at least one platform defined.    |
+| publish.publishedName        | [Optional, default is the project name] The name of the resulting artifacts upon publishing.          |
+| publish.publishNumber        | [Optional default is 1] the publishing version number (typically incremented with each release).      |
+| publish.iconsDir             | [Optional] The directory housing all project icons, must follow the [configurations](#-custom-icons). |
+| publish.generateMissingIcons | [Optional, default is false] try to generate missing icons base on `iconsDir` attribute content.      |
+
+For instance (minimal, only required attributes):
 ```json
 {
   "title" : "OIS simulation", 
@@ -135,41 +137,85 @@ For instance:
     "Green" : "org.example.GreenState"
   },
   "publish" : {
-    "platforms" : [ "Desktop" ]
+    "platforms" : [ "Desktop", "Android" ]
   }
 }
 ```
 
-### Custom Icons
-
-You have the opportunity to tailor your own custom icons for the project.
-A designated directory should be provided to accommodate these icons.
-You are not obliged to provide a complete set of icons; any missing icons will be substituted with default counterparts.
-
-The directory must contain only one item per combination of dimensions and extensions.
-If multiple items exist, only one will be considered.
-
-The valid extensions for icons are: `png`, `ico`, `icns`.
-
-Acceptable icon dimensions include: `128x128`, `32x32`, `16x16`.
-
 ### Plugin Extension
 For seamless development, the option to override specific project `simulation.ois` or plugin configurations is available.
 This can be achieved by specifying the `oisDeployer` extension within your `build.gradle` file:
 
 ```groovy
 oisDeployer {
     // Instead of resolving the runner based on its version in simulation.ois, 
-    // run the runner project from this directory.
+    // Run the runner project from this directory.
     runnerPath = 'path-to-dir-of-specific-runner'
     // Instead of retrieving the project configurations from the `simulation.ois` file in the project root directory,
-    // obtain project configurations from this file.
+    // Obtain project configurations from this file.
     configPath = 'path-to-your-simulation-config-file'
-    // Rather than resolving the assets directory from your project resources, resolve it from this path.
+    // Rather than resolving the assets directory from your project resources
+    // Resolve it from this path.
     assetsPath = 'path-to-your-resources-dir'
+    // Rather than resolving the Android Sdk location from the environment variable 'ANDROID_HOME'
+    // Resolve it from this path.
+    androidSdkPath = 'path-to-android-sdk-dir'
 }
 ```
 
+### 🖼️ Custom Icons
+
+You have the opportunity to tailor your own custom icons for the project.
+A designated directory should be provided to accommodate these icons.
+You are not obliged to provide a complete set of icons; any missing icons will be substituted with default counterparts,
+or generated from the existing subset.
+
+The directory must contain only one item per combination of dimensions and extensions.
+If multiple items exist, only one will be considered.
+
+<details>
+<summary>Desktop Platform Icons</summary>
+
+---
+
+The valid extensions for icons are:
+* **Windows:** `png`, `ico` (optional).
+* **Linux:** `png`.
+* **Mac:** `icns`.
+
+Acceptable icon dimensions include: `128x128`, `32x32`.
+
+---
+</details>
+
+<details>
+<summary>Android Platform Icons</summary>
+
+---
+
+The icon that will be shown as the app has to be in `xml` format and be generated by following this steps:
+1. **Generate your Icon**.
+   * Must be in `svg` / `psd` format. 
+   * Colors must be in black and white (can color shapes later).
+   * Must be `108x108`, the logo should be centered, must be at least `48x48` dp; it must not exceed `72x72` dp because the inner `72x72` dp of the icon appears within the masked viewport.
+2. **Open, in intellij, any `Android` project** (or use the runner project cloned to the `ois` plugin directory in your `$HOME` directory).
+   
+    2.1. On the Project tab, right click: `New` -> `Vector Asset`
+
+    2.2. Chose `Asset type` value to `Local file (SVG, PSD)` the path and the target name.
+
+    2.3. Chose `108dpx108dp` as the value for `Sizw`.
+
+    2.4. Continue and generate the `xml` file and copy it to your `iconsDir`.
+ 
+3. **[Optional] Color** the generated icon shapes (`paths` tag) by editing the `xml` file and changing their `fillColor` values.
+
+In addition, you can provide `png` icons for specific dpi,
+Acceptable icon dimensions include: `48x48`, `72x72`, `96x96`, `144x144`, `192x192`.
+
+---
+</details>
+
 ---
 ## 🏗️ How to Use
 
@@ -193,10 +239,33 @@ for insights into leveraging the core library effectively.
 
 ### 👀 Running Your Project
 
-After applying the [configurations](#-project-configurations), you can run your project locally on your `Desktop` by executing:
+To plugin will create running tasks to debug your project for each value you input at `publish.platforms` attribute in the [configurations](#-project-configurations).
+
+<details>
+<summary>Desktop Platform</summary>
+
+---
+After applying the configurations, you can run your project locally on your `Desktop` by executing:
    ```bash
    gradlew runDesktop
    ```
+---
+</details>
+
+<details>
+<summary>Android Platform</summary>
+
+---
+After applying the configurations, you can run your project on a virtual/physical `Android` device by executing:
+1. Make sure there is an active device connected (can use Intellij).
+2. Run the following gradle command:
+   ```bash
+   gradlew runAndroid
+   ```
+> Some changes may require to uninstall the application before rerunning.
+---
+</details>
+
 
 ### 🚀 Distributing Your Project
 
@@ -206,14 +275,18 @@ These files are essential for running your project on the designated platforms.
    gradlew deployProject
    ```
 
-> **Distributing on the Desktop Platform:**
-> 
-> Note that the generated zip files are specific to the platform they were built on. 
-> For instance, generate the distribution task on a Windows machine for Windows distribution and on a Linux machine for Linux distribution.
-
 The artifacts intended for distribution will be created within your project's `build` directory.
 Inside this directory, you'll find a folder named `OIS` containing zip files tailored for each platform configuration specified in your project's configuration file.
 
+> **Publishing to Desktop Platform:**
+>
+> Note that the generated zip files are specific to the platform they were built on.
+> For instance, generate the distribution task on a Windows machine for Windows distribution and on a Linux machine for Linux distribution.
+
+> **Publishing to Android Platform:**
+> 
+> Note that the generated apk is unsigned and should be signed before distribution.
+
 ---
 ## 🐞 Reporting Issues
 
@@ -222,7 +295,7 @@ we recommend using the `-d` option when running Gradle for detailed debug inform
 
 If you face issues with running or deploying your project, start fresh by cleaning the runners:
 ```bash
-    gradlew cleanRunners
+gradlew cleanRunners
 ```
 
 To contribute to the library's improvement, 

diff --git a/build.gradle b/build.gradle
@@ -7,13 +7,17 @@ group 'org.attias.open.interactive.simulation'
 version '1.0-SNAPSHOT'
 var pluginDescription = "Plugin that can run and deploy simulation made by OpenSimualtion"
 
+ext {
+    coreVersion = '0.1'
+}
+
 repositories {
     mavenCentral()
     mavenLocal()
 }
 
 dependencies {
-    implementation group: 'org.attias.open.interactive.simulation', name: 'open-interactive-simulation-core', version: '0.1'
+    api "org.attias.open.interactive.simulation:open-interactive-simulation-core:$coreVersion"
 
     implementation 'org.eclipse.jgit:org.eclipse.jgit:6.6.0.202305301015-r'
 

diff --git a/src/main/java/org/attias/open/interactive/simulation/deployer/Constant.java b/src/main/java/org/attias/open/interactive/simulation/deployer/Constant.java
@@ -17,15 +17,18 @@ public class Constant {
 
     // The group of the tasks added by the plugin
     public static final String GROUP_NAME = ProjectUtils.OIS;
-
+    // the name of the plugin directory at home user
+    public static final String OIS_DIRECTORY_NAME = "." + ProjectUtils.OIS;
     // The plugin directory in the user home
-    public static final Path HOME_PATH = Paths.get(System.getProperty("user.home"), ProjectUtils.OIS_DIRECTORY_NAME);
+    public static final Path HOME_PATH = Paths.get(System.getProperty("user.home"), OIS_DIRECTORY_NAME);
     // The directory that cache the runners
     public static final Path RUNNERS_PATH = HOME_PATH.resolve("runners");
     // The version of the runners compatible with the plugin version
     public static final String RUNNER_VERSION = "0.1";
-    // Minimum Gradle version to run the plugin
+    // Minimum Gradle version to run the plugin - for desktop publish
     public static final Version MIN_GRADLE_VERSION = new Version("7.0.0");
+    // Minimum Java version to run the plugin - for desktop publish
+    public static final Version MIN_JAVA_VERSION = new Version("15");
     // The default name that will be when simulation.ois is created
     public static final String DEFAULT_PROJECT_TITLE = "OIS Simulation";
     public static final Set<AppConfiguration.AppType> APP_TYPES = new HashSet<>(List.of(AppConfiguration.AppType.Desktop));
@@ -48,6 +51,9 @@ public class Constant {
     public static final String RUN_DESKTOP_TASK_NAME = "runDesktop";
     public static final String RUN_DESKTOP_TASK_DESCRIPTION = "Runs the simulation using desktop";
 
+    public static final String RUN_ANDROID_TASK_NAME = "runAndroid";
+    public static final String RUN_ANDROID_TASK_DESCRIPTION = "Runs the simulation using android device";
+
     public static final String DEPLOY_TASK_NAME = "deployProject";
     public static final String DEPLOY_TASK_DESCRIPTION = "Deploy the project to production files for each platform";
 }
diff --git a/...ain/java/org/attias/open/interactive/simulation/deployer/SimulationDeployerExtension.java b/...ain/java/org/attias/open/interactive/simulation/deployer/SimulationDeployerExtension.java
@@ -7,6 +7,7 @@ public class SimulationDeployerExtension {
     private String configPath;
     private String runnerPath;
     private String assetsPath;
+    private String androidSdkPath;
 
     public SimulationDeployerExtension(Project project) {
         this.project = project;
@@ -35,4 +36,12 @@ public String getAssetsPath() {
     public void setAssetsPath(String assetsPath) {
         this.assetsPath = assetsPath;
     }
+
+    public String getAndroidSdkPath() {
+        return androidSdkPath;
+    }
+
+    public void setAndroidSdkPath(String androidSdkPath) {
+        this.androidSdkPath = androidSdkPath;
+    }
 }