Commit ae473a15 authored by Lionel Seinturier's avatar Lionel Seinturier
Browse files

Deprecated. See dedicated project.

parent 5ce94ea8
image: maven:3.5.2-jdk-9-slim
before_script:
- export MAVEN_OPTS="-Xms256m -Xmx512m -Dmaven.repo.local=.m2/repository"
cache:
paths:
- .m2/repository
test:
stage: test
script:
- mvn -B -Pjuliac:tests,juliac:examples install
============================================================================
Juliac
Copyright (C) 2007-2018 Inria, Univ. Lille 1
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Contact: fractal@ow2.org
Author: Lionel Seinturier
============================================================================
============================================================================
Juliac
Copyright (C) 2007-2018 Inria, Univ. Lille 1
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Contact: fractal@ow2.org
Author: Lionel Seinturier
Contributors:
Loris Bouzonnet, Olivier Dalle, Damien Fournier, Jonathan Labejof,
Frederic Loiret, Philippe Merle, Christophe Munilla, Victor Noel,
Judicael Ribault, Romain Rouvoy, Valerio Schiavoni
============================================================================
Juliac 2.7
----------
Juliac is a framework for generating and compiling the source code of the
infrastructure (so called membranes) that is needed to run a Fractal/Java
application. The application can then be run without having to use ASM to
generate on-the-fly classes for interfaces, controllers and merge strategies.
Juliac is an alternative to Julia in cases where dynamic code generation and
loading is problematic. The idea behind Juliac is close to that of Think
(but for Java of course). Currently, four optimization levels have been
implemented in Juliac: MERGE_ALL, OO (controllers implemented as separate
objects), COMP (component-based control membranes) and ULTRA_MERGE. Juliac can
be configured to accept other user-defined optimization levels.
The name Juliac stands for "Julia Compiler" and was proposed by Philippe Merle.
Juliac is a free software distributed under the terms of the GNU Lesser
General Public license. Juliac is written in Java.
Table of content
----------------
1. Requirements
2. Introduction
3. Compiling and installing Juliac
4. Running the sample applications
5. Compiling and running your own applications
6. References
1. Requirements
---------------
Maven 2.0.x is required to compile and run Juliac.
See http://maven.apache.org for instructions on downloading and using Maven.
2. Introduction
---------------
Juliac is composed of:
- all: the superset of all Juliac Maven artifacts (excluding extension),
- api: the core API of Juliac,
- commons: common utility functions,
- core: the code generation framework,
- examples: sample applications and tests,
- extension: extensions to Juliac,
- module: modules for Juliac (ADL parsers, compilers, generators, Spoon),
- mojo: a Maven plugin for Juliac,
- runtime: the library needed to run an application compiled with Juliac.
The following samples applications are available in the examples directory:
- comanche: the Comanche web server application,
- helloworld: the Fractal Hello World application.
In addition the examples/advanced directory contains some advanced samples. See
the README.txt in the corresponding directories to obtain more information about
these samples.
- comp-based-membrane: programming a custom component-based control membrane,
- foobar-cases: FooBar examples,
- helloworld-bin: binary components (compiled classes) with Juliac,
- helloworld-janino: the Fractal Hello World example with the Janino compiler,
- helloworld-mindadl: the Fractal Hello World example with the Mind ADL,
- large: large component assemblies,
- mix: the Fractal Hello World example with different optimization levels,
- ultra-merge: examples with the ultra-merge optimization level.
The extension directory contains some extensions to Juliac:
- adlet: the support of annotated architecture descriptors,
- dream: the support for Dream and COSMOS frameworks,
- fraclet: the support for Fraclet annotated Fractal components,
- osgi: the support for OSGi Equinox, Felix, JBoss, Knopflerfish frameworks,
- scala: the support for the Scala language.
3. Compiling and installing Juliac
----------------------------------
To compile and install Juliac in your Maven local repository, from the root
directory where Juliac has been installed, type:
mvn install
4. Running the sample applications
----------------------------------
To compile and run the sample applications, type:
cd examples/xxx (where xxx is the directory name of the sample)
mvn -Pjuliac:run
5. Compiling and running your own applications
----------------------------------------------
The quickest way for using Juliac is to mimic the organization of the
examples/helloworld module. The source and the resources of the application
should be put under respectively, src/main/java and src/main/resources.
5.1 Compiling
-------------
A Maven plugin is available for compiling applications with Juliac. As
illustrated in the examples/helloworld module, the plugin can be configured as
follows:
01 <build>
02 <plugins>
03 <plugin>
04 <groupId>org.ow2.fractal.juliac</groupId>
05 <artifactId>maven-juliac-plugin</artifactId>
06 <version>2.6</version>
07 <executions>
08 <execution>
09 <id>juliac-compile</id>
10 <phase>generate-sources</phase>
11 <goals><goal>compile</goal></goals>
12 </execution>
13 </executions>
14 <configuration>
15 <srcs><src>src/main/java</src></srcs>
16 <adls><adl>example.hw.HelloWorld</adl></adls>
17 <modules>
18 <module>JCAPI</module>
19 <module>FRACTAL_ADL</module>
20 <module>OO</module>
21 </modules>
22 </configuration>
23 </plugin>
24 </plugins>
25 </build>
Lines 14 to 22 in the <configuration> section particularly matter for the
configuration of Juliac. The following tags are supported:
- <srcs> list of directories containing the source code of the application,
- <adls> list of Fractal-ADL types to be compiled by Juliac,
- <modules> list of modules to be loaded by Juliac.
See http://fractal.ow2.org/juliac-mojo for additional information about the
Juliac Maven plugin.
5.2 Running
-----------
Once compiled with Juliac, applications can be run with the
org.objectweb.fractal.juliac.runtime.Juliac Fractal provider class. The
<juliac.run.component> and <juliac.run.interface> properties allow specifying
respectively, the component and the interface to invoke. These properties
configure the juliac:run profile that is defined in juliac/pom.xml.
For example, when configured with:
<juliac.run.component>example.hw.HelloWorld</juliac.run.component>
<juliac.run.interface>r</juliac.run.interface>
the command:
mvn -Pjuliac:run
launches the example.hw.HelloWorld component by invoking the interface named r.
5.3 Optimization levels
-----------------------
Four optimization levels have been implemented and may be specified in the <opt>
tag:
- COMP: component-based control membranes (Juliac version of Koch),
- MERGE_ALL: the content, the control and the interceptors are merged,
- OO: controllers are implemented as independent objects,
- ULTRA_MERGE: a non-reconfigurable version of the application is generated in
one unique class.
In addition, a custom optimization level may be specified. In this case, the
value of the <opt> tag must be the fully-qualified name of a class that
implements the org.objectweb.fractal.juliac.FCSourceCodeGeneratorItf interface.
6. References
-------------
- Cosmos : http://picoforge.int-evry.fr/projects/svn/cosmos
- Dream : http://dream.ow2.org
- Equinox : http://www.eclipse.org/equinox
- Felix : http://felix.apache.org
- Fractal : http://fractal.ow2.org
- Fractal ADL : http://fractal.ow2.org/fractaladl
- Janino : http://docs.codehaus.org/display/JANINO
- JBoss OSGi : http://community.jboss.org/wiki/JBossOSGi
- Julia : http://fractal.ow2.org/julia
- Knopflerfish : http://www.knopflerfish.org
- Maven : http://maven.apache.org
- MIND : http://mind.ow2.org
- OSA : http://osa.gforge.inria.fr
- OSGi Alliance : http://www.osgi.org
- Scala : http://www.scala-lang.org
- Spoon : http://spoon.gforge.inria.fr
For any question, please contact: fractal@ow2.org
Date of creation of this file: 4 June 2007.
Last modified: 21 June 2016.
Juliac 2.7
----------
* new api module with Juliac core API
* new extension Adlet for annotated architecture descriptors
* bug fix for the OSGi bundle-ization of the juliac-runtime artifact
* move to Java compliance level 1.8
* move to Spoon 6.1 and JDT 3.13.50.v20171007-0855
* move to Scala 2.12.1
Juliac 2.6
----------
* support for Fraclet-annotated Fractal components
* MOJO renamed to juliac-maven-plugin to comply with the Maven conventions
(suggested by Victor Noel)
* module JDK6 renamed to JCAPI
* move to Spoon 4.2.0 and EJC 4.4
* new extension for the Open Simulation Architecture (OSA)
Released on 14 July 2015
http://mail.ow2.org/wws/arc/fractal/2015-07/msg00001.html
Juliac 2.5.1
------------
* bug fixes
Released on 20 March 2013
Juliac 2.5
----------
* API Refactoring: JuliacModuleItf is the new root interface for all modules
(ADL parsers, optimization level source code generators, compilers, Spoon)
* MOJO
* <modules> tag renamed to <artifacts>
* <modules> tag for ADL parsers, compiler, and Spoon
* new directory module replaces opt and plugin
* groupId org.ow2 replaces org.objectweb
* Concierge, JBoss OSGi, and Knopflerfish support (contributed by Christophe M)
* Janino compiler support (suggested by Philippe)
* Maven 3 MOJO
Released on 3 December 2012
Juliac 2.4
----------
* OSGi/Knopflerfish support (contributed by Christophe Munilla)
* API refactoring
* bug fix when generating the membrane factory: support membrane types where the
first type is not necessarily the component control interface
* Juliet annotation definitions moved to Fraclet
* new service for generating proxy (interface and interceptor) implementations
(requested by Remi M and Philippe)
* multiple ADL parsers support
* move to Fraclet 3.3
Released on 7 April 2011
Juliac 2.3
----------
* API refactoring
* extended code generation framework (contributed by Romain)
* Juliet annotation framework for defining membranes
* new testCompile goal in the Juliac MOJO for the generate-test-sources phase
Released on 5 February 2011
Juliac 2.2.6.1
--------------
* new gracefulExit option in the Juliac MOJO configuration to exit without
throwing an exception even if errors are reported
Released on 27 October 2010
Juliac 2.2.6
------------
* UnifiedClass API enhanced with new methods
* --igs option renamed to --icodegs
* new --iclassgs for specifying association between bytecode interceptor class
generator and source code ones
Released on 23 October 2010
Juliac 2.2.5.1
--------------
* fix proxy generation for generic methods to enable compilation with javac
Released on 3 September 2010
Juliac 2.2.5
------------
* enable configuring the ADL parser used by Juliac
* separate ADL parser code generation from optimization level code generation
* support for the MIND ADL
* better support for generic proxy generation with generics (contributed by
Jonathan)
* upgrade to Maven MOJO librairies version 2.2.1
Released on 20 July 2010
Juliac 2.2.4
------------
* new --genclassjar option for packaging compiled generated classes in a jar
* bug fix when generating interceptor implementations for generic interfaces
with more than one interceptor source code generator (reported by Philippe)
* when invoking Juliac from the command line, support component descriptors of
the form [component type, controller descriptor, content descriptor]
* new --compilationWarnings flag for reporting compilation warnings (requested
by Philippe)
Released on March 20, 2010
Juliac 2.2.3
------------
* artifact juliac-compiler renamed to juliac-core
* artifact juliac-dream-compiler renamed to juliac-dream-core
* new --compiler option for specifying the Java compiler to use
* new extension for compiling generated code with the JDK 6 Compilation API
* bug fix for proxy code generation associated with interfaces which specialize
the return type of an inherited method (reported by Loris)
* support for the Equinox OSGi platform in extension/osgi
Released on 1 November 2009
Juliac 2.2.2
------------
* MOJO
* optimization levels are specified with the tags <opts> and <namespaces>
* fix for artifacts with alphabetical version numbers (e.g. 2.4-alpha-4)
* configurable source code and bytecode compatibility levels
* a main(String[]) method is generated for assembly factories with a r/Runnable
server interface
* new example with the Scala programming language (contributed by Romain)
* optimization level source code generators
* ultra-merge: bug fix for architecture descriptors containing cycles between
components (reported by Frederic)
* OO: reduce the size of initializer classes by factorizing the code which is
common for each membrane (suggested by Philippe)
Released on 22 September 2009
Juliac 2.2.1
------------
* API changes: Juliac, optimization level source code generators
* tighter integration between the Spoon and JDT plugins
* the Spoon plugin retrieves the AST build by JDT via the JDT plugin
* library upgrades
* extension/dream: Dream Core 2.2
* extension/dream/examples/cosmos-helloword: Cosmos 0.1.5
* plugin/jdt: JDT 3.3.0.771
* plugin/spoon: Spoon 1.4.2
* extension/osgi
* Activator source code generator for bundling a Fractal assembly
Released on 3 July 2009
Juliac 2.2
----------
* API changes: optimization level source code generators
* bug fix in classpaths containing path names with white space characters when
invoking the JDT plugin
Released on 7 May 2009
Juliac 2.1.6
------------
* API changes: Fractal ADL plugin, optimization level source code generators
* new extension module for holding extensions to Juliac
* support source files stored in jar files
* new extension module for supporting OSGi/Felix osgiPrimitive membranes
* bug fix for the NORMAL mode of the simple interceptor source code generator
(reported by Alban)
* use the JDK logging API for reporting
Released on 13 March 2009
Juliac 2.1.5
------------
* new --pkgRoot option for rooting generated code in a given package
(requested by Loris)
* multiple optimization levels with the same controller descriptor prefix can be
specified
* manage internal interfaces when generating the code for mComposite components
* bug fix for the MOJO
* when managing dependencies retain the most recent version number of a
library
* artifact and module renaming for advanced Dream examples
* bug fix for plugin JDT on MacOS (contributed by Valerio)
Released on 23 January 2009
http://mail.ow2.org/wws/arc/fractal/2009-01/msg00014.html
Juliac 2.1.4
------------
* new advanced example for Dream/Cosmos
* lifecycle interceptors are generated per lifecycle controller
* new JuliacConfig class for handling several Juliac configurations
* handle component factories for large assemblies (reported by Judicael)
* due to the 64KB limit imposed by Java on method bytecode size, component
factories are split into several methods
Released on 20 November 2008
Juliac 2.1.3
------------
* refactor JuliacLoader
Released on 27 October 2008
Juliac 2.1.2
------------
* bug fix for the <mixin> tag of the MOJO (exclude transitive dependencies)
* add a classloader interface to the Juliac bootstrap component
Released on 11 October 2008
Juliac 2.1.1
------------
* bug fix for component interfaces with generics (reported by Damien)
Released on 21 September 2008
Juliac 2.1
----------
* structured configuration parameters for the MOJO
* <types> replaced by <adls>
* list-like tags for <adls> <modules> <mixins> <srcs>
e.g. <adls> <adl>...</adl> <adl>...</adl> ... <adl>...</adl> </adls>
* <components> MOJO parameter for generating the code corresponding to the
specified component types, membrane descriptors and content descriptors
* <compile> MOJO parameter replaced by <compileInput> and <compileGenerated> for
compiling respectively input and generated code (default values are true)
* --compile command line argument replaced by --compileInput and
--compileGenerated for compiling respectively input and generated code
(default values are false)
* handle absolute pathnames in command line arguments and MOJO parameters
* handle generic parameters when generating proxy classes
* Juliac API changes
* class Juliac: methods parseOptLevel and parseInterceptorGenerators replaced
by loadGenerators
* class JuliacParams extended with 2 new fields opt and igs of type String
with values taken from the corresponding configuration parameters
(either from the command line or the MOJO)
Released on 12 September 2008
http://mail.ow2.org/wws/arc/fractal/2008-09/msg00012.html
Juliac 2.0.2
------------
* bug fix with artifacts for default optimization levels
* use the plugin version number, not the project one (reported by Damien)
Released on 5 July 2008
Juliac 2.0.1
------------
* JDT compilation support: Improved reporting of error messages
* bug fix in code generation with inner types (reported by Fy)
Released on 3 July 2008
http://mail.ow2.org/wws/arc/fractal/2008-07/msg00012.html
Juliac 2.0
----------
* Maven groupId changed to org.objectweb.fractal.juliac
* Fractal ADL no longer mandatory (optional module)
* new juliac-runtime-comp module for applications with component-based membranes
* Juliac MOJO
* artifacts specified in the <mixins> and <modules> sections and artifacts for
default optimization levels (OO, COMP, MERGE_ALL and ULTRA_MERGE) are
automatically added to the classpath
* generated source code can be compiled by the regular Maven compile phase
Released on 30 June 2008
http://mail.ow2.org/wws/arc/fractal/2008-07/msg00005.html
Juliac 1.3
----------
* move to Fractal ADL 2.3
* custom class loader can be transmitted to the Juliac component factory
* new optimization level: ultra-merge
* package refactoring to increase independence between subsystems
* examples module refactored with basic and advanced samples
* artifact identifiers renamed with a juliac- prefix
* add a juliac-all artifact
Released on 22 May 2008
http://mail.ow2.org/wws/arc/fractal/2008-05/msg00003.html
Juliac 1.2
----------
* move to Fractal ADL 2.2
* custom architecture generation for user-specified optimization levels
Released on 31 January 2008
http://mail.ow2.org/wws/arc/fractal/2008-01/msg00143.html
Juliac 1.1
----------
* user-specified Fractal ADL factory and backend
(fractaladl.factory and fractaladl.backend system properties)
* interceptor on control interfaces
* FileSourceCodeVisitor interface in the source code visitor framework
* code generation for membranes independently of any content
* pre-mixed Julia control membranes (OO and COMP merge levels)
Released on 23 December 2007
http://mail.ow2.org/wws/arc/fractal/2007-12/msg00041.html
Juliac 1.0
----------
* 3 merge levels: OO, COMP and MERGE_ALL
* join use of different merge levels for the same application
Released on 27 October 2007
http://mail.ow2.org/wws/arc/fractal/2007-10/msg00104.html
core/
* dump generated files to disk only when one is sure that the generation process
is over and everything went right. The purpose is to prevent generating
incomplete code that cannot be compiled. The issue arised with the
<gracefulExit> MOJO option. The issue was partially solved in r10816 (see
Juliac#generateSourceCodeOverride(ClassGeneratorItf)), by first generating
code in memory and then dumping the code onto disk once the generation is over
and has thus been completed without error. Yet the solution is not fully
satisfactory as it may happen that files in a group may be dependent from each
others, and in this case the compilation would still fail with a missing type
exception. The issue may arise for example when generating an initializer
class that references other generated types such as interceptor, interface or
controller implementations.
* when Juliac is invoked programmatically, support in memory code generation and
compilation when no value is defined for the --gensrc and --genclass
parameters. Retain the current behavior to generate in the default locations
for the MOJO and the command line.
* provide a --gensrcjar for packaging the generated source code in a jar file
* expose Juliac as a Fractal provider class.
The idea is to generated the source code during the first run of the
application in order to be able to reuse it for later runs.
* proxy generation
* fix generic type variable conflicts between the implemented interface and
the extended class. This conflict occurs for example in Tinfi when
generating proxies for generic interfaces (e.g.
BindingFactoryPlugin<E extends ExportHints, B extends BindHints>) from
the Binding Factory. In this case, the extended class is ServiceReference<B>
and the identifier B clashes with the one from BindingFactoryPlugin.
* provide a command line option for generating proxy (interface and interceptor)
implementations similar to the <proxy><signature><controllerDesc> parameters
available for the MOJO.
extension/osgi/
* support OSGi properties (requested by Philippe)
* enable changing the bundle which is associated with a osgiPrimitive component
(suggestion by Valerio)
mojo/
* mvn clean checks the availability of the maven-juliac-plugin even though this
plugin is not required when performing mvn clean. This causes mvn clean to
fail if the MOJO has not been installed before (bug reported by Denis.)
* re-investigate with recent versions of Java the way class loaders are built.
The idea would be to retrieve a class loader that would have been built by
Maven based on the plugin dependency specifications only, and not on custom
artifact resolution. Taking inspiration from the Maven exec MOJO would be a
good idea.
module/
* investigate a new optimization level source code generator which takes place
between mergeall and ultra-merge. The idea is to keep business objects as this
and to generate a Java factory that instantiates the assembly using reflection
without any infrastructure (membrane, interceptor, interface object) code.