core/runtime/src/docs/runtime.txt

//////////////////////
 *  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you under the Apache License, Version 2.0 (the
 *  "License"); you may not use this file except in compliance
 *  with the License.  You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
//////////////////////

[[core-runtime,Core Runtime]]
= Core Runtime =

[devstatus]
--------------
source=core/runtime/dev-status.xml
--------------

First of all, your code should never, ever, have a dependency on Core Runtime. If you think you need this, you should
probably contact users@zest.apache.org mailing list and see if your usecase can either be solved in a existing way or
perhaps that a new Core SPI Extension is needed.

include::../../build/docs/buildinfo/artifact.txt[]

Let's repeat that; *Never, never, ever depend on Core Runtime*. Make sure that the compile dependency does NOT include
the `org.apache.zest.core.runtime` jar.

== Custom AssemblyHelper ==
BUT, there are super-rare cases, where a custom AssemblyHelper might be needed. One known use-case is tp introduce
an alternative bytecode generation algorithm, either better than the one we have, or for a different system, such
as Dalvik.

To do this, add the +AssemblyHelper+ implementation instance as +metaInfo+ to the +ApplicationAssembly+

We think this is so rare, that the +AssemblyHelper+ class will remain in the +core/runtime+ module and has not
been promoted to the +core/bootstrap+ module. If you plan to use this feature, please contact the Zest development
team at +dev@zest.apache.org+ to ensure we can make this a better supported, backed by real usecases.

Fictitious example of using a hypothetical Dalvik capable classloader;

[source,java]
--------------
source=core/runtime/src/test/java/org/apache/zest/runtime/bootstrap/DocumentationSupport.java
tag=customAssemblyHelper
--------------