WIP 633 Add prototype for multiple apps in single project

[muuki88]

Prototype

This is the first attempt to provide multiple start scripts within a single project. The main idea is to leverage the already provided script by JavaAppPackaging and just forward calls to it. This results in

• the default start script (using the mainClass in Compile defined class`=
• scripts for all `discoveredMainClasses in Compile)

Usage

Assuming two main classes com.example.DefaultMain and com.example.AnotherMain.

enablePlugins(JavaAppPackaging, ScriptPerMainClass)

mainClass in Compile := Some("com.example.DefaultMain")

sbt stage will create the following output

target/universal/stage
├── bin
│   ├── another-main
│   ├── default-main
│   ├── test-project-simple
│   └── test-project-simple.bat
├── conf
│   └── application.ini
└── lib
    ├── com.typesafe.config-1.2.1.jar
    ├── default.test-project-simple-0.2.0.jar
    └── org.scala-lang.scala-library-2.10.4.jar

TODOs

• Tests need to be fixed and/or extended
• Documentation is missing
• Bat script plugin is missing
• Application.ini refactoring still needs to be done

[muuki88]

comments welcome: @metasim , @wookietreiber , @kardapoltsev

[wookietreiber]

First of all thank you for considering this use case and providing an implementation for it. I have a few questions regarding your code samples:

1. What is the purpose of bin/test-project-simple[.bat]?
2. Why do you set mainClass in Compile? When scripts are created for all detected main classes, setting this should be superfluous.

[muuki88]

What is the purpose of bin/test-project-simple[.bat]?

This is generated by the JavaAppPackaging. This initial version won't support windows, so there is only one bat file.

Why do you set mainClass in Compile? When scripts are created for all detected main classes, setting this should be superfluous.

I though of two options.

1. Generate the bash-template script for each main class, replicating the template and just alter the main class
2. Generate small scripts that call the default start script and only override the -main parameter.

I went for the second option, which I thought reduces duplicated bash scripts. On the other hand this generates the confusing default script. Hm.

[wookietreiber]

1. Generate the bash-template script for each main class, replicating the template and just alter the main class
2. Generate small scripts that call the default start script and only override the -main parameter.

I would generally prefer the first option.

---

I can think of two use cases for multiple apps within one project:

1. There are multiple apps of equal importance.

In this case I would definitely want to not have the default start script. This, of course, requires that the scripts are all self-contained and not rely on calling the default script.
2. There is a main app, bundled with some supplementary utility apps.

In this case, I would want to have the default start script, possibly named after the project instead of its respective main class. Here it would be ok if the supplementary are small scripts that call the default one.

---

To support both use cases, I do not know if it is better to either have different plugins, i.e. ScriptPerMainClass and e.g. MainWithUtilities, or to have only one plugin, e.g. MultipleMainClasses, where an sbt setting deciding which way to go.

[metasim]

@muuki88 No particular thoughts. I'm glad it's implemented via a plugin, and that separate launch scripts are created. javapackager has the ability to deploy two launchers, so long term would be interesting to see if it could automatically leverage this.

One question: how do you control the number of launcher scripts that are generated? Is there a task you can override to filter the found main classes?

[muuki88]

Thanks a lot for the input.

@wookietreiber you are right. These are both valid use cases. I think I would implement them both in one plugin and switch between them via a setting.

how do you control the number of launcher scripts that are generated? Is there a task you can override to filter the found main classes?

@metasim not yet. I was not sure if this should be added in the first version as "too many" start scripts won't hurt and you can always filter them via the mappings in Universal. If I add this, I thought of something like mainClassToScriptName = settingKey[String => Option[String]].

[muuki88]

WDYT of the following idea.

1. ScriptPerMainClass is enabled by default, when JavaAppPackaging is enabled
2. If there's only one main class, the plugin does nothing
3. If there are multiple main classes the plugin has two different behaviors
   1. If mainClass in Compile is set explicitly, forwarder scripts will be generated ( like @wookietreiber MainWithUtilities suggested )
   2. If no mainClass in Compile is set, equal important scripts will be generated for each main

Customization can be done by

• disablePlugin(ScriptPerMainClass) to disable script generating
• mainClassToScriptName for custom script names

[metasim]

I was not sure if this should be added in the first version as "too many" start scripts won't hurt and you can always filter them via the mappings in Universal. If I add this, I thought of something like mainClassToScriptName = settingKey[String => Option[String]].

I like that, because it allows a) name transformation, and b) filtering.

Are Class names really "stringly typed" in sbt?

[muuki88]

@metasim . Yes, Classes are "stringly typed".

[muuki88]

@kardapoltsev / @metasim could you take a look? If you think the behaviour is okay, I'll merge this and release. You can use the github review feature to do so :)

[metasim]

I suggest clarifying the semantics of "forwarder scripts" in the docs, and how to disable their generation.

[metasim]

What is meant by "forwarding scripts"? Maybe flesh out the semantic difference, and/or indicate details follow.

[muuki88]

True. I'm still not happy with the naming anyway. Forwarder, Delegate,..
However I will define the semantics more clearly.

[metasim]

Here I might go into a bit more detail on the differences between the main start script and what it means to have a "forwarder". Also, how do you disable the generation of forwarders?