Migrating {N} Android Plugins from version 1.7 to 2.0

The quick guide to handle a necessary breaking change in plugin structure.

As the {N} project progresses and we grow up with it, there will always be need for change. In this case a breaking change. Don’t worry, it’s not as dire as it sounds at first, but I would recommend reading the article anyway. After all, “A few hours of coding can save a few minutes of reading the documentation”.

What will the plugin look like after the migration?

after migration	before migration
+-- index.js +-- package.json +-- MyModule1/ ¦    +-- index1.js ¦    +-- package.json +-- MyModule2/ ¦    +-- index2.js ¦    +-- package.json +-- platforms/     +-- android/          +-- myLibrary.jar         +-- myLibrary.aar         +-- include.gradle	+-- index.js +-- package.json +-- MyModule1/ ¦    +-- index1.js ¦    +-- package.json +-- MyModule2/ ¦    +-- index2.js ¦    +-- package.json +-- platforms/     +-- android/          +-- myLibrary.jar         +-- myLibrary.aar         +-- include.gradle         +-- AndroidManifest.xml            +-- res/

The plugin migration will affect only the platforms/android folder and nothing else.

What possible question you may have after seeing the new structure?

• What happened to the AndroidManifest.xml? Where am I supposed to put my configurations?
  There are two options:
  
  You can simply move the content of the platforms/android/AndroidManifest.xml to the .aar’s AndroidManifest.xml. In case you don’t know what an .aar file is: it’s the output from an Android Studio module project. As you can see in this specification the .aar project structure has an AndroidManifest.xml.
  
  The second option is far easier. Since 1.6 release there is an AndroidManifest.xml in app/App_Resources/Android/ and you can put all configurations there.
  
  
• What happened to the res/ folder? How can I use resources that can be declared in the manifest?
  That’s what the .aar is for. if you look again at the .aar specification you will see you have everything you need there and more.
  
  
• What about the .jar files that need some additional configurations in the AndroidManifest.xml?
  Same as before. Either build an .aar file or go to app/App_Resources/Android/AndroidManifest.xml and put the necessary configurations there.
  
  
• Are there any other changes?
  Yes, but the good news is, they are delete only. You need to go to the include.gradle file, if you have one, and delete the first block of code entirely.
  //default elements

  android {

      productFlavors {

          "my-plugin" {

              dimension "my-plugin"

          }

      }

  }
  
  This code will no longer be necessary and there will no longer be problems on Windows with path being too long, because of concatenation of the productFlavors names.
  
  

Why do we need this change?

As you can see in the android gradle plugin documentation the .aar files are  therecommended way of using dependencies in the gradle build system. With the change concerning the plugin structure, we’ll get all the advantages gradle has to offer, without any of the disadvantages we had up till now. Let me give you some examples of why the current structure has problems.

• Case 1
  ...

  +-- platforms/

      +-- android/

          +-- myLibrary.jar

          +-- AndroidManifest.xml
  
  

  When the AndroidManifest.xml is out in the open like that, if there are other plugins that also have an AndroidManifest.xml file and at some point they will have to be merged together. Currently there is no easy way for that to happen and we need to take additional steps to ensure the right output. When using .aar format, this is done automatically by gradle.

• Case 2
  
  ...

  +-- platforms/

      +-- android/

           +-- myLibrary.jar

          +-- myLibrary.aar

          +-- AndroidManifest.xml
  
  Ok we have an AndroidManifest.xml, but the .aar file also has an AndroidManifest.xml file as we saw in the .aar specification, so why should we have two, when we can only have one, that the gradle system will take care of merging not only the manifest but all assets you have put in the .aar file.
  
  
• Case 3
  
  ...

  +-- platforms/

      +-- android/

          +-- myLibrary.jar

          +-- AndroidManifest.xml

          +--res/
  
  Well you have .jar and the .aar file has .jar.
  You have AndroidManifest.xml and the .aar file has AndroidManifest.xml.
  You have res/ and the .aar file has res/.
  I think you can see my point. You need an .aar package, instead of some flying files that the gradle build system has no way of easily merging and using.

Useful information for plugin developers.

If you are a {N} plugin developer you and you want your plugins to be verified, till now we only required a sample app, but now we need sample app + unit tests before you can claim you plugin to be verified.