# HG changeset patch # User Jaroslav Tulach # Date 1450852671 -3600 # Node ID 579d21e36582acce158b1409e00fe3ef8a23d732 # Parent 6ab54020385366f1ae8b86e782358f25cddde93a Including documentation for the TCK in the unified Javadoc diff -r 6ab540203853 -r 579d21e36582 truffle/com.oracle.truffle.tck/src/com/oracle/truffle/tck/TruffleTCK.java --- 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 TCK) 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 protected methods and include in your test suite: + * + * 
+ * public class MyLanguageTCKTest extends {@link TruffleTCK} {
+ *   {@link Override @Override}
+ *   protected {@link PolyglotEngine} {@link #prepareVM() prepareVM}() {
+ *     // create the engine
+ *     // execute necessary scripts
+ *   }
+ * 
+ *   {@link Override @Override}
+ *   protected {@link String} fourtyTwo() {
+ *     return // name of function that returns 42
+ *   }
+ * 
+ *   // and so on...
+ * }
+ *
+ * + * The TCK is carefully designed to accommodate differences between languages. The + * TCK doesn't dictate what object your language is using to represent {@link Number + * numbers} or {@link String strings} internally. The TCK 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 + * TCK 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: + * + * 
+ *   {@link Override @Override}
+ *   public void {@link #testFortyTwo() testFortyTwo}() {
+ *     // do nothing
+ *   }
+ *
+ *

+ * The primary goal of the TCK 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 + * TCK 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. + *

+ * Should the TCK be found unsuitable for your {@link TruffleLanguage language + * implementation} please speak-up (at Truffle/Graal mailing list for example) and we do + * our best to analyze your case and adjust the TCK to suite everyone's needs. */ public abstract class TruffleTCK { private static final Random RANDOM = new Random(); diff -r 6ab540203853 -r 579d21e36582 truffle/com.oracle.truffle.tck/src/com/oracle/truffle/tck/package-info.java --- /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; +