Mercurial > hg > truffle
changeset 22524:579d21e36582
Including documentation for the TCK in the unified Javadoc
author | Jaroslav Tulach <jaroslav.tulach@oracle.com> |
---|---|
date | Wed, 23 Dec 2015 07:37:51 +0100 |
parents | 6ab540203853 |
children | 89db2519ef18 |
files | truffle/com.oracle.truffle.tck/src/com/oracle/truffle/tck/TruffleTCK.java truffle/com.oracle.truffle.tck/src/com/oracle/truffle/tck/package-info.java |
diffstat | 2 files changed, 95 insertions(+), 3 deletions(-) [+] |
line wrap: on
line diff
--- a/truffle/com.oracle.truffle.tck/src/com/oracle/truffle/tck/TruffleTCK.java Tue Dec 22 18:00:04 2015 +0100 +++ b/truffle/com.oracle.truffle.tck/src/com/oracle/truffle/tck/TruffleTCK.java Wed Dec 23 07:37:51 2015 +0100 @@ -42,18 +42,73 @@ import org.junit.Test; import com.oracle.truffle.api.TruffleLanguage; +import com.oracle.truffle.api.interop.ForeignAccess.Factory10; +import com.oracle.truffle.api.interop.Message; import com.oracle.truffle.api.interop.TruffleObject; import com.oracle.truffle.api.interop.java.JavaInterop; import com.oracle.truffle.api.interop.java.MethodMessage; +import com.oracle.truffle.api.nodes.RootNode; import com.oracle.truffle.api.source.Source; import com.oracle.truffle.api.vm.PolyglotEngine; import com.oracle.truffle.api.vm.PolyglotEngine.Language; import com.oracle.truffle.tck.Schema.Type; /** - * A collection of tests that can certify language implementation to be compliant with most recent - * requirements of the Truffle infrastructure and tooling. Subclass, implement abstract methods and - * include in your test suite. + * Test compatibility kit (the <em>TCK</em>) is a collection of tests to certify your + * {@link TruffleLanguage language implementation} compliance. If you want your language to be + * compliant with most recent requirements of the Truffle infrastructure and tooling, subclass, + * implement <b>protected</b> methods and include in your test suite: + * + * <pre> + * <b>public class</b> MyLanguageTCKTest <b>extends</b> {@link TruffleTCK} { + * {@link Override @Override} + * <b>protected</b> {@link PolyglotEngine} {@link #prepareVM() prepareVM}() { + * <em>// create the engine</em> + * <em>// execute necessary scripts</em> + * } + * + * {@link Override @Override} + * <b>protected</b> {@link String} fourtyTwo() { + * <b>return</b> <em>// name of function that returns 42</em> + * } + * + * <em>// and so on...</em> + * } + * </pre> + * + * The <em>TCK</em> is carefully designed to accommodate differences between languages. The + * <em>TCK</em> doesn't dictate what object your language is using to represent {@link Number + * numbers} or {@link String strings} internally. The <em>TCK</em> doesn't prescribe the precise + * type of values returned from your + * {@link PolyglotEngine#eval(com.oracle.truffle.api.source.Source) language evaluations}. The tests + * just assume that if the result is supposed to be a number, the returned value will be an instance + * of {@link Number} or be {@link Message#UNBOX convertible} to a {@link Number} and keeps + * sufficient level of precision. Similarly for {@link String strings}. As such the tests in the + * <em>TCK</em> should be applicable to wide range of languages. Should there be a test that cannot + * be implemented in your language, it can be suppressed by overriding its test method and doing + * nothing: + * + * <pre> + * {@link Override @Override} + * <b>public void</b> {@link #testFortyTwo() testFortyTwo}() { + * <em>// do nothing</em> + * } + * </pre> + * <p> + * The primary goal of the <em>TCK</em> is to ensure your {@link TruffleLanguage language + * implementation} plays well with other languages in the {@link PolyglotEngine} - e.g. that data + * can be exchanged between your and other languages. The {@link com.oracle.truffle.api.interop + * interop package} defines what types of data can be interchanged between the languages and the + * <em>TCK</em> does its best to make sure all these data are really accepted as an input on a + * boundary of your {@link TruffleLanguage language implementation}. That doesn't mean such data + * need to be used internally, many languages do conversions in their {@link Factory10 foreign + * access} {@link RootNode nodes} to more suitable internal representation. Such conversion is fully + * acceptable as nobody prescribes what is the actual type of output after executing a function/code + * snippet in your language. + * <p> + * Should the <em>TCK</em> be found unsuitable for your {@link TruffleLanguage language + * implementation} please speak-up (at <em>Truffle/Graal</em> mailing list for example) and we do + * our best to analyze your case and adjust the <em>TCK</em> to suite everyone's needs. */ public abstract class TruffleTCK { private static final Random RANDOM = new Random();
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/truffle/com.oracle.truffle.tck/src/com/oracle/truffle/tck/package-info.java Wed Dec 23 07:37:51 2015 +0100 @@ -0,0 +1,37 @@ +/* + * Copyright (c) 2015, Oracle and/or its affiliates. All rights reserved. + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * This code is free software; you can redistribute it and/or modify it + * under the terms of the GNU General Public License version 2 only, as + * published by the Free Software Foundation. Oracle designates this + * particular file as subject to the "Classpath" exception as provided + * by Oracle in the LICENSE file that accompanied this code. + * + * This code 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 General Public License + * version 2 for more details (a copy is included in the LICENSE file that + * accompanied this code). + * + * You should have received a copy of the GNU General Public License version + * 2 along with this work; if not, write to the Free Software Foundation, + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. + * + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA + * or visit www.oracle.com if you need additional information or have any + * questions. + */ + +/* + @ApiInfo( + group="Test Compatibility Kit" + ) + */ + +/** + * Include implementation of {@link com.oracle.truffle.tck.TruffleTCK} in your test suite to verify + * your {@link com.oracle.truffle.api.TruffleLanguage language} implementation is compliant. + */ +package com.oracle.truffle.tck; +