Project structure

From DEMUX Framework Wiki
Jump to: navigation, search

This article describes project structure when building applications with DEMUX Framework. Project structure is predefined, so all projects can be built consistently and with minimal effort from user. Each project type can be created automatically using Maven archetype. Each project type is defined bellow.

Contents

JavaFX applications

This is the project type for creating desktop applications based on JavaFX. It provides complete development lifecycle: writing, compiling, debugging, testing and deployment. Each task is automated and required minimal input from user. This type of project is created using demux-jfx-archetype. This archetype is available in Maven Central repository. To use this archetype, simply type the following command line:

mvn archetype:generate -Dfilter=com.vektorsoft.demux.tools:demux-jfx-archetype

Enter required information: group ID, artifact ID (e.g. myproject), version and DEMUX Framework version. Once this is complete, you will get the following file structure:

myproject
 |--config
 |--pom.xml
 |--antrun-build.xml

File pom.xml is Maven project POM, and antrun-build.xml is an Ant build file used for some tasks during application development. Directory config contains configuration files needed to build platform-specific installer pacakges. It is discussed in more details in later sections. At this point, you can build and install application. After that is completed, you will see additional files and directories:

myproject
 |-target
   |-dist
     myproject-1.0.0
      |-bundles
      |-osgi.jar
      |-demux-desktop-jfx.jar
 |--pom.xml
 |--antrun-build.xml
 |-config.properties

Each of these new file and directories are described bellow:

  • target/dist - distribution directory. This is where all output files reside
  • myproject-1.0.0 - top-level application directory. Think of it as installation directory for application. This is also working directory where JVM is invoked when application is run. The name of directory is in form {artifactId}-{version}
  • bundles - directory where application OSGI bundles are stored
  • osgi.jar - OSGI runtime. This JAR is part of application classpath
  • demux-desktop-jfx - JAR containing main class for DEMUX Framework JavaFX application
  • config.properties - this file contains some configuration properties for correct build. It is always generated on each build.

Maintaining this project structure is critical for correct build/run/debug lifecycle. Each time the project is built, this structure is updated. When you run application during development, Maven invokes JVM with work directory set to application output directory (target/dist/myproject-1.0.0 in this case). JVM is invoked with demux-desktop-jfx.jar as executable JAR. When application starts, it will look for bundles inside bundles directory.

Handling dependencies

For DEMUX Framework, project dependencies are treated as OSGI bundles. If you take a closer look at pom.xml, you can see that most dependencies are declared with scpope provided. This is because build system assumes that these are OSGI bundles, and thus dynamic in nature. It means that they should be available at runtime, and are treated as external dependencies of application. Build scripts are configured so that they copy these dependencies (with scope provided) into bundles directory, from where they are loaded at runtime.

When declaring your own dependencies (if they are OSGI bundles), you should declare them in top-level POM, so that they get handled correctly. This is the case even if dependencies are used by only a single bundle. If, however, your dependencies are plain old JAR files, you can declare them in bundle submodule POMs.

Configuration files

As we mentioned before, directory config contains configuration files needed to build platforms-specific installer packages. Contents of this file are shown bellow:

config
 |--common
 |    |--myproject.desktop
 |    |--launcher.ini
 |--deb
 |    |--control
 |    |--postinst
 |--mac
 |    |--Info.plist
 |--nsis
      |--JREDyna_Inetc.nsh
      |--setup.nsi

  • common - contains files common for multiple installers
    • launcher.ini - .ini file for launcher startup. Contains options for installer startup for each platform
    • myproject.desktop - this is Linux application desktop file. It is placed in KDE/GNOME menu and contains application icon etc. It's name matches artifactId set in Maven project
  • deb - contains configuration files for creating DEB packages
    • control - control file for package creation
    • postinst - post installation script which sets executable flag for launcher
  • mac - contains configuration files for creating Mac OS X application bundles
    • Info.plist - bundle information file
  • nsis - configuration files for creating Windows NSIS installer
    • JREDyna_Inetc.nsh - header script which will check for required JRE, and download and install one if not present
    • setup.nsi - main setup script


DEMUX Bundle project

This type of project creates OSGI bundle for DEMUX Framework. Since DEMUX is based on OSGI, bundles are the smallest deployment unit for the code, and so the building blocks of every DEMUX Framework application. We provide Maven archetype for creating this type of project. Archetype is called demux-bundle-archetype.

Projects based on DEMUX Framework are actually Maven multi-module projects. Each bundle is a separate module project, with top-level project, such as JavaFX project we described above, is the parent. So, in order to generate bundle project, archetype must be invoked from parent project directory.

cd myproject
mvn archetype:generate -Dfilter=com.vektorsoft.demux.tools:demux-bundle-archetype

This will create simple Maven project structure. The only additional file is antrun-build.xml, which is used to perform some specific tasks during the build. If you look at project POM, you can see that packaging type is bundle, which means that output is packaged as OSGI bundle. To configure to your own needs, simply edit configuration of mave-bundle-plugin in pom.xml. More about this plugin's configuration can be found on plugin web page.

Most of the time during development, you will change only one bundle at a time. You don't have to rebuild entire top-level project, only the changed bundle. When built, it will be automatically copied to correct location, so the application can be run with new changes.

When Maven install phase is run on bundle, it will copy resulting bundle .jar to correct location of parent project, depending on type of parent project.

  • For JavaFX project, bundle will be copied to target/dist/<artifactId>-<version>/bundles directory of parent project
  • For Android project, it will be copied into app/assets/bundles directory of parent project

DEMUX Android project

To get started with developing applications for Android, DEMUX Framework provides another Maven archetype. Create your Android project using the following command:

mvn archetype:generate -Dfilter=com.vektorsoft.demux.tools:demux-android-archetype

Select the latest version, and fill in required properties, as shown bellow. Note that package here refers to Android application package, as you would use when creating project with Android tools.

1: remote -> com.vektorsoft.demux.tools:demux-android-archetype (Create Android application structure for DEMUX Framework applications)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 1
Choose com.vektorsoft.demux.tools:demux-android-archetype version: 
1: 0.4.0
2: 0.5.0
Choose a number: 2: 2
Define value for property 'groupId': : com.test
Define value for property 'artifactId': : testapp
Define value for property 'version':  1.0-SNAPSHOT: : 1.0.0
Define value for property 'package':  com.test: : 
Define value for property 'demuxFrameworkVersion': : 0.5.0

This will generate project testapp in current directory. Project structure is shown bellow:

testapp
 |--app
 |   |--libs
 |   |--res
 |   |--src
 |   |--AndroidManifest.xml
 |   |--ant.properties
 |   |--antrun-build.xml
 |   |--build.xml
 |   |--local.properties
 |   |--pom.xml
 |--pom.xml

To-level directory testapp is Maven parent project, while submodule app contains actual Android project structure as would be created by creating Android tools. This directory will contain final output (.apk files).

Note: Make sure that in file local.properties property sdk.dir has the value of path to Android SDK installation on your development machine. This should be generated automatically if you have ANDROID_HOME environment variable set.

To start working, create new bundle project in top level directory, like discussed in previous section. This will be a bundle that will be added to our Android application. When you finish editing bundle project, you can simply build entire application by invoking the following command in top-level directory

mvn install
mvn deploy -pl app

This will do the following:

  • copy OSGI runtime and DEMUX module needed to start up a framework into app/libs directory
  • copy all dependencies declared with scope provided to app/assets/bundles directory. We assume here that all OSGI dependencies need for application are declared with scope provided
  • build each child bundle we created and copy resulting .jar into app/assets/bundles
  • run DEX tool on all jars inside app/assets/bundles to create .dex files (if not already present)

When build completes, you will get fully-funtional .apk in app/bin directory. You can then deploy this file to device or emulator at will.

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox