You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@calcite.apache.org by jh...@apache.org on 2014/08/02 03:29:11 UTC
[4/5] git commit: Add README file, incubation disclaimers,
and HOWTO build and running tests.
Add README file, incubation disclaimers, and HOWTO build and running tests.
The README file (as distinct from README.md) is intended to be the first file that someone reads when they have downloaded a source or binary release.
In README.md, add a disclaimer about incubation status, rename Optiq to Apache Optiq, and move documentation into HOWTO.md.
Project: http://git-wip-us.apache.org/repos/asf/incubator-optiq/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-optiq/commit/d3531d43
Tree: http://git-wip-us.apache.org/repos/asf/incubator-optiq/tree/d3531d43
Diff: http://git-wip-us.apache.org/repos/asf/incubator-optiq/diff/d3531d43
Branch: refs/heads/master
Commit: d3531d43d05c96180654a627ced844c2279ece41
Parents: ab15a72
Author: Julian Hyde <jh...@apache.org>
Authored: Fri Aug 1 15:47:52 2014 -0700
Committer: Julian Hyde <jh...@apache.org>
Committed: Fri Aug 1 17:42:22 2014 -0700
----------------------------------------------------------------------
HOWTO.md | 137 ++++++++++++++++++++++++++++++++++++++++++++++++------
NOTICE | 31 ++----------
README | 28 +++++++++++
README.md | 37 +++++++--------
REFERENCE.md | 2 +-
5 files changed, 176 insertions(+), 59 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-optiq/blob/d3531d43/HOWTO.md
----------------------------------------------------------------------
diff --git a/HOWTO.md b/HOWTO.md
index e61a0e7..5c1a3f3 100644
--- a/HOWTO.md
+++ b/HOWTO.md
@@ -3,7 +3,103 @@
Here's some miscellaneous documentation about using Optiq and its various
adapters.
-# Tracing
+## Building from a source distribution
+
+Prerequisites are maven (3.0.4 or later)
+and Java (JDK 1.6 or later, 1.8 preferred) on your path.
+
+Unpack the source distribution `.tar.gz` or `.zip` file,
+`cd` to the root directory of the unpacked source,
+then build using maven:
+
+```bash
+$ tar xvfz apache-optiq-0.9.0-incubating-source.tar.gz
+$ cd apache-optiq-0.9.0-incubating
+$ mvn install
+```
+
+[Running tests](HOWTO.md#running-tests) describes how to run more or fewer
+tests.
+
+## Building from git
+
+Prerequisites are git, maven (3.0.4 or later)
+and Java (JDK 1.6 or later, 1.8 preferred) on your path.
+
+Create a local copy of the github repository,
+`cd` to its root directory,
+then build using maven:
+
+```bash
+$ git clone git://github.com/apache/incubator-optiq.git
+$ cd incubator-optiq
+$ mvn install
+```
+
+[Running tests](HOWTO.md#running-tests) describes how to run more or fewer
+tests.
+
+## Running tests
+
+The test suite will run by default when you build, unless you specify
+`-DskipTests`:
+
+```bash
+$ mvn -DskipTests clean install
+```
+
+There are other options that control which tests are run, and in what
+environment, as follows.
+
+* `-Doptiq.test.db=DB` (where db is `hsqldb` or `mysql`) allows you
+ to change the JDBC data source for the test suite. Optiq's test
+ suite requires a JDBC data source populated with the foodmart data
+ set.
+ * `hsqldb`, the default, uses an in-memory hsqldb database.
+ * `mysql` uses a MySQL database in `jdbc:mysql://localhost/foodmart`.
+ It is somewhat faster than hsqldb, but you need to populate it
+ manually.
+* `-Doptiq.debug` prints extra debugging information to stdout.
+* `-Doptiq.test.slow` enables tests that take longer to execute. For
+ example, there are tests that create virtual TPC-H and TPC-DS schemas
+ in-memory and run tests from those benchmarks.
+* `-Doptiq.test.mongodb=true` enables tests that run against
+ MongoDB. MongoDB must be installed, running, and
+ [populated with the zips.json data set](HOWTO.md#mongodb-adapter).
+* `-Doptiq.test.splunk=true` enables tests that run against Splunk.
+ Splunk must be installed and running.
+
+## Contributing
+
+We welcome contributions.
+
+If you are planning to make a large contribution, talk to us first! It
+helps to agree on the general approach. Log a
+[JIRA case](https://issues.apache.org/jira/browse/OPTIQ) for your
+proposed feature or start a discussion on the dev list.
+
+Fork the github repository, and create a branch for your feature.
+
+Develop your feature and test cases, and make sure that `mvn clean
+install` succeeds. (Run extra tests if your change warrants it.)
+
+Commit your change to your branch, and use a comment that starts with
+the JIRA case number, like this:
+
+```
+[OPTIQ-345] AssertionError in RexToLixTranslator comparing to date literal
+```
+
+If your change had multiple commits, use `git rebase -i master` to
+combine them into a single commit, and to bring your code up to date
+with the latest on the main line.
+
+Then push your commit(s) to github, and create a pull request from
+your branch to the incubator-optiq master branch. Update the JIRA case
+to reference your pull request, and a committer will review your
+changes.
+
+## Tracing
To enable tracing, add the following flags to the java command line:
@@ -36,12 +132,12 @@ fairly verbose outout. You can modify the file to enable other loggers, or to ch
For instance, if you change FINER to FINEST the planner will give you an account of the
planning process so detailed that it might fill up your hard drive.
-# CSV adapter
+## CSV adapter
See <a href="https://github.com/julianhyde/optiq-csv/blob/master/TUTORIAL.md">optiq-csv
tutorial</a>.
-# MongoDB adapter
+## MongoDB adapter
First, download and install Optiq,
and <a href="http://www.mongodb.org/downloads">install MongoDB</a>.
@@ -100,7 +196,7 @@ Closing: net.hydromatic.optiq.jdbc.FactoryJdbc41$OptiqConnectionJdbc41
$
```
-# Splunk adapter
+## Splunk adapter
To run the test suite and sample queries against Splunk,
load Splunk's `tutorialdata.zip` data set as described in
@@ -110,7 +206,7 @@ load Splunk's `tutorialdata.zip` data set as described in
queries. It is also necessary if you intend to run the test suite, using
`-Doptiq.test.splunk=true`.)
-# Implementing adapters
+## Implementing an adapter
New adapters can be created by implementing `OptiqPrepare.Context`:
@@ -135,9 +231,15 @@ public class AdapterContext implements OptiqPrepare.Context {
}
```
-## Testing adapter in Java
+### Testing adapter in Java
-The example below shows how SQL query can be submitted to `OptiqPrepare` with a custom context (`AdapterContext` in this case). Optiq prepares and implements the query execution, using the resources provided by the `Context`. `OptiqPrepare.PrepareResult` provides access to the underlying enumerable and methods for enumeration. The enumerable itself can naturally be some adapter specific implementation.
+The example below shows how SQL query can be submitted to
+`OptiqPrepare` with a custom context (`AdapterContext` in this
+case). Optiq prepares and implements the query execution, using the
+resources provided by the `Context`. `OptiqPrepare.PrepareResult`
+provides access to the underlying enumerable and methods for
+enumeration. The enumerable itself can naturally be some adapter
+specific implementation.
```java
import net.hydromatic.optiq.jdbc.OptiqPrepare;
@@ -162,16 +264,21 @@ public class AdapterContextTest {
## JavaTypeFactory
-When Optiq compares `Type` instances, it requires them to be the same object. If there are two distinct `Type` instances that refer to the same Java type, Optiq may fail to recognize that they match.
-It is recommended to
+When Optiq compares `Type` instances, it requires them to be the same
+object. If there are two distinct `Type` instances that refer to the
+same Java type, Optiq may fail to recognize that they match. It is
+recommended to:
- Use a single instance of `JavaTypeFactory` within the optiq context
- Store the `Type` instances so that the same object is always returned for the same `Type`.
## Set up PGP signing keys (for Optiq committers)
-Follow instructions at http://www.apache.org/dev/release-signing to create a key pair. (On Mac OS X, I did `brew install gpg` and `gpg --gen-key`.)
+Follow instructions at http://www.apache.org/dev/release-signing to
+create a key pair. (On Mac OS X, I did `brew install gpg` and `gpg
+--gen-key`.)
-Add your public key to the `KEYS` file by following instructions in the `KEYS` file.
+Add your public key to the `KEYS` file by following instructions in
+the `KEYS` file.
## Making a snapshot (for Optiq committers)
@@ -197,7 +304,9 @@ When the dry-run has succeeded, change `install` to `deploy`.
Before you start:
* Set up signing keys as described above.
* Make sure you are using JDK 1.7 (not 1.6 or 1.8).
-* Make sure build and tests succeed, including with -Doptiq.test.db={mysql,hsqldb}, -Doptiq.test.slow=true, -Doptiq.test.mongodb=true, -Doptiq.test.splunk=true.
+* Make sure build and tests succeed, including with
+ -Doptiq.test.db={mysql,hsqldb}, -Doptiq.test.slow=true,
+ -Doptiq.test.mongodb=true, -Doptiq.test.splunk=true.
```bash
# set passphrase variable without putting it into shell history
@@ -209,7 +318,9 @@ git clean -x
```
Check the artifacts:
-* Make sure that binary and source distros have a README file (README.md does not count) and that the version in the README is correct
+* Make sure that binary and source distros have a README file
+ (README.md does not count) and that the version in the README is
+ correct
* The file name must start `apache-optiq-` and include `incubating`.
* Check PGP, per https://httpd.apache.org/dev/verification.html
http://git-wip-us.apache.org/repos/asf/incubator-optiq/blob/d3531d43/NOTICE
----------------------------------------------------------------------
diff --git a/NOTICE b/NOTICE
index d180150..fd9f5dc 100644
--- a/NOTICE
+++ b/NOTICE
@@ -1,28 +1,7 @@
-optiq
-Copyright (C) 2012-2014 Julian Hyde
+Apache Optiq
+Copyright 2012-2014 The Apache Software Foundation
-===============================================================================
-This product includes software from the Eigenbase project, licensed from
-DynamoBI Corporation, http://github.com/dynamobi/luciddb/.
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
-Copyright (C) 2005-2011 DynamoBI Corporation.
-
-===============================================================================
-This software includes code from the Guava project,
-released under the Apache License, Version 2.0,
-and available from https://code.google.com/p/guava-libraries/.
-
-Copyright (C) 2007 The Guava Authors
-
-===============================================================================
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this software 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.
+Please see LICENSE for additional copyright and licensing information.
http://git-wip-us.apache.org/repos/asf/incubator-optiq/blob/d3531d43/README
----------------------------------------------------------------------
diff --git a/README b/README
new file mode 100644
index 0000000..bacc4ad
--- /dev/null
+++ b/README
@@ -0,0 +1,28 @@
+Apache Optiq release 0.9.0 (incubating)
+
+This is a source or binary distribution of Apache Optiq.
+
+Changes since the previous release are described in the HISTORY.md
+file.
+
+The LICENSE and NOTICE files contain license information.
+
+If this is a source distribution, you can find instructions how to
+build the release in the "Building from a source release" section in
+HOWTO.md.
+
+README.md contains examples of running Optiq.
+
+Further information about Apache Optiq is available at its web site,
+http://incubator.apache.org/optiq.
+
+Disclaimer
+
+Apache Optiq is an effort undergoing incubation at The Apache Software
+Foundation (ASF), sponsored by the Apache Incubator. Incubation is
+required of all newly accepted projects until a further review
+indicates that the infrastructure, communications, and decision making
+process have stabilized in a manner consistent with other successful
+ASF projects. While incubation status is not necessarily a reflection
+of the completeness or stability of the code, it does indicate that
+the project has yet to be fully endorsed by the ASF.
http://git-wip-us.apache.org/repos/asf/incubator-optiq/blob/d3531d43/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 7f651fb..2d2bc0d 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,16 @@
[](https://travis-ci.org/julianhyde/optiq)
-optiq
-=====
+# Apache Optiq
-Optiq is a dynamic data management framework.
+Apache Optiq is a dynamic data management framework.
-Prerequisites
-=============
+## Getting Optiq
-Optiq requires git, maven (3.0.4 or later), and JDK 1.6 or later (JDK 1.7 preferred).
+To run Apache Optiq, you can either
+[download a release](http://www.apache.org/dyn/closer.cgi/incubator/optiq)
+or [build from the source code](HOWTO.md#building-from-a-source-distribution).
-Download and build
-==================
-
-```bash
-$ git clone git://github.com/julianhyde/optiq.git
-$ cd optiq
-$ mvn install
-```
-
-Use `mvn -DskipTests` if you do not want to execute the tests.
-
-Example
-=======
+## Example
Optiq makes data anywhere, of any format, look like a database. For
example, you can execute a complex ANSI-standard SQL statement on
@@ -210,3 +198,14 @@ Please don't post to the mailing list.
* <a href="https://github.com/julianhyde/share/blob/master/slides/optiq-nosql-now-2013.pdf?raw=true">SQL Now!</a> (NoSQL Now! conference, 2013)
* <a href="https://github.com/julianhyde/share/blob/master/slides/hive-cbo-summit-2014.pdf?raw=true">Cost-based optimization in Hive</a> (Hadoop Summit, 2014)
* <a href="https://github.com/julianhyde/share/blob/master/slides/dmmq-summit-2014.pdf?raw=true">Discardable, in-memory materialized query for Hadoop</a> (Hadoop Summit, 2014)
+
+## Disclaimer
+
+Apache Optiq is an effort undergoing incubation at The Apache Software
+Foundation (ASF), sponsored by the Apache Incubator. Incubation is
+required of all newly accepted projects until a further review
+indicates that the infrastructure, communications, and decision making
+process have stabilized in a manner consistent with other successful
+ASF projects. While incubation status is not necessarily a reflection
+of the completeness or stability of the code, it does indicate that
+the project has yet to be fully endorsed by the ASF.
http://git-wip-us.apache.org/repos/asf/incubator-optiq/blob/d3531d43/REFERENCE.md
----------------------------------------------------------------------
diff --git a/REFERENCE.md b/REFERENCE.md
index 92f54eb..c1338a4 100644
--- a/REFERENCE.md
+++ b/REFERENCE.md
@@ -114,7 +114,7 @@ name will have been converted to upper case also.
| BIGINT | 8 byte signed integer | Range is -9223372036854775808 to 9223372036854775807
| DECIMAL(p, s) | Fixed point | Example: 123.45 is a DECIMAL(5, 2) value.
| NUMERIC | Fixed point |
-| REAL, FLOAT | 4 byte floating point | 6 decimal digits precision
+| REAL, FLOAT | 4 byte floating point | 6 decimal digits precision
| DOUBLE | 8 byte floating point | 15 decimal digits precision
| CHAR(n), CHARACTER(n) | Fixed-width character string | 'Hello', '' (empty string), _latin1'Hello', n'Hello', _UTF16'Hello', 'Hello' 'there' (literal split into multiple parts)
| VARCHAR(n), CHARACTER VARYING(n) | Variable-length character string | As CHAR(n)