Generate all APIs.

This CL expands the generator to create all the .rsh files, not just
the core_math one.  To do so, processing of types (simple, struct, enums)
and constants was added.  .spec files corresponding to each .rsh file was
created.  Documentation was added.

This CL also generates HTML documentation files.  This generation will soon
be upgraded.

To make the code easier to expand, I've done fairly extensive refactoring.

In a subsequent CL, the APIs will be regrouped in different header files to
simplify learning the APIs.  In an other, the documentation generation will
be futher improved and incorporated in the actual online help.

Also removes rs_path & related functions.

Change-Id: I2c88554c9c6a8625233772b89e055fc6c4ad5da5

1 files changed, 202 insertions, 0 deletions

diff --git a/api/Generator.cpp b/api/Generator.cpp
new file mode 100644
index 00000000..376364ce
--- /dev/null
+++ b/api/Generator.cpp
@@ -0,0 +1,202 @@
+/*
+ * Copyright (C) 2013 The Android Open Source Project
+ *
+ * Licensed 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.
+ */
+
+/* This program processes Renderscript function definitions described in spec files.
+ * For each spec file provided on the command line, it generates a corresponding
+ * Renderscript header (*.rsh) which is meant for inclusion in client scripts.
+ *
+ * This program also generates Junit test files to automatically test each of the
+ * functions using randomly generated data.  We create two files for each function:
+ * - a Renderscript file named Test{Function}.rs,
+ * - a Junit file named Test{function}.java, which calls the above RS file.
+ *
+ * Finally, this program generates HTML documentation files.
+ *
+ * This program takes an optional -v parameter, the RS version to target the
+ * test files for.  The header file will always contain all the functions.
+ *
+ * This program contains five main classes:
+ * - SpecFile: Represents on spec file.
+ * - Function: Each instance represents a function, like clamp.  Even though the
+ *      spec file contains many entries for clamp, we'll only have one clamp instance.
+ * - FunctionSpecification: Defines one of the many variations of the function.  There's
+ *      a one to one correspondance between FunctionSpecification objects and entries in the
+ *      spec file.  Strings that are parts of a FunctionSpecification can include placeholders,
+ *      which are "#1", "#2", "#3", and "#4".  We'll replace these by values before
+ *      generating the files.
+ * - Permutation: A concrete version of a specification, where all placeholders have
+ *      been replaced by actual values.
+ * - ParameterDefinition: A definition of a parameter of a concrete function.
+ *
+ * The format of the .spec files is described below.  Line that starts with # are comments.
+ * Replace the {} sections with your own contents.  [] indicates optional parts.
+ *
+ * It should start with a header as follows:
+ *
+ * header:
+ * summary:  {A one line string describing this section.}
+ * description:
+ *     {Multiline description.  Can include HTML.  References to constants, types,
+ *      and functions can be created by prefixing with a '@'.}
+ * [include:
+ *     { Multiline code lines to be included as-is in the generated header file.}]
+ * end:
+ *
+ * Constants are defined as follows:
+ *
+ * constant:  {The name of the constant.}
+ * [version: {Starting API level} [ {Last API level that supports this.}]
+ * [size: {32 or 64.  Used if this is available only for 32 or 64 bit code.}]
+ * value: {The value of the constant.}
+ * [hidden:]   ...If present, don't document the constant.  Omit the following two fields.
+ * summary: {A one line string describing this section.}
+ * description:
+ *     {Multiline description.  Can include HTML.  References to constants, types,
+ *      and functions can be created by prefixing with a '@'.}
+ * end:
+ *
+ * Types can either be simple types, structs, or enums.  They have the format:
+ *
+ * type:  {The typedef name of the type.}
+ * [version: {Starting API level} [ {Last API level that supports this.}]
+ * [size: {32 or 64.  Used if this is available only for 32 or 64 bit code.}]
+ * simple: {The C declaration that this type is the typedef equivalent.}
+ * [hidden:]   ...If present, don't document the type.  Omit the following two fields.
+ * summary: {A one line string describing this section.}
+ * description:
+ *     {Multiline description.  Can include HTML.  References to constants, types,
+ *      and functions can be created by prefixing with a '@'.}
+ * end:
+ *
+ * type:  {The typedef name of the type.}
+ * [version: {Starting API level} [ {Last API level that supports this.}]
+ * [size: {32 or 64.  Used if this is available only for 32 or 64 bit code.}]
+ * struct: [{The name that will appear right after the struct keyword}]
+ * field: {Type and name of the field}[, "{One line documentation of the field}"]
+ * field:   ... Same for all the other fields of the struct.
+ * [attrib: {Attributes of the struct.}]
+ * [hidden:]   ...If present, don't document the type.  Omit the following two fields.
+ * summary: {A one line string describing this section.}
+ * description:
+ *     {Multiline description.  Can include HTML.  References to constants, types,
+ *      and functions can be created by prefixing with a '@'.}
+ * end:
+ *
+ * type:  {The typedef name of the type.}
+ * [version: {Starting API level} [ {Last API level that supports this.}]
+ * [size: {32 or 64.  Used if this is available only for 32 or 64 bit code.}]
+ * enum: [{The name that will appear right after the enum keyword}]
+ * value: {Type and name of the field}[, "{One line documentation of the field}"]
+ * value:   ... Same for all the other values of the enum.
+ * [hidden:]   ...If present, don't document the type.  Omit the following two fields.
+ * summary: {A one line string describing this section.}
+ * description:
+ *     {Multiline description.  Can include HTML.  References to constants, types,
+ *      and functions can be created by prefixing with a '@'.}
+ * end:
+
+ * Functions have the following format:
+ *
+ * function:  {The name of the function.}
+ * [version: {Starting API level} [ {Last API level that supports this.}]
+ * [size: {32 or 64.  Used if this is available only for 32 or 64 bit code.}]
+ * [attrib: {Attributes of the function.}]
+ * [w: {A comma separated list of width supported.  Only 1, 2, 3, 4 are supported.
+ * [t: {A comma separated list of the types supported.}]]
+ * ... Up to four w: or t: can be defined.  The order matter.  These will be replace
+ * ... the #1, #2, #3, #4 that can be found in the rest of the specification.
+ * ret: [{The return type} [, "{One line documentation of the return}"]]
+ * [arg: {Type}[, {Name}][, {ParameterEntry.testOption}][, "{One line documentation of the field}"]]
+ * [arg:   ... Same for all the other arguments of the function.]
+ * [hidden:]   ... If present, don't include in the HTML documentation.
+ * summary: {A one line string describing this section.}
+ * description:
+ *     {Multiline description.  Can include HTML.  References to constants, types,
+ *      and functions can be created by prefixing with a '@'.}
+ * [inline:
+ *     {Multiline code that implements this function inline.}]
+ * [test: {How to test this function.  See FunctionSpecification::mTest.}]
+ * end:
+ */
+
+#include <stdio.h>
+#include <cctype>
+#include <cstdlib>
+#include <fstream>
+#include <functional>
+#include <iostream>
+#include <memory>
+#include <sstream>
+#include <strings.h>
+
+#include "Generator.h"
+#include "Scanner.h"
+#include "Specification.h"
+#include "Utilities.h"
+
+using namespace std;
+
+static bool parseCommandLine(int argc, char* argv[], int* versionOfTestFiles,
+                             vector<string>* specFileNames) {
+    for (int i = 1; i < argc; i++) {
+        if (argv[i][0] == '-') {
+            if (argv[i][1] == 'v') {
+                i++;
+                if (i < argc) {
+                    char* end;
+                    *versionOfTestFiles = strtol(argv[i], &end, 10);
+                    if (*end != '\0') {
+                        cerr << "Error. Can't parse the version number" << argv[i] << "\n";
+                        return false;
+                    }
+                } else {
+                    cerr << "Missing version number after -v\n";
+                    return false;
+                }
+            } else {
+                cerr << "Unrecognized flag %s\n" << argv[i] << "\n";
+                return false;
+            }
+        } else {
+            specFileNames->push_back(argv[i]);
+        }
+    }
+    if (specFileNames->size() == 0) {
+        cerr << "No spec file specified\n";
+        return false;
+    }
+    return true;
+}
+
+int main(int argc, char* argv[]) {
+    // If there's no restriction, generated test files for the very highest version.
+    int versionOfTestFiles = 999999;
+    vector<string> specFileNames;
+    if (!parseCommandLine(argc, argv, &versionOfTestFiles, &specFileNames)) {
+        cout << "Usage: gen_runtime spec_file [spec_file...] [-v version_of_test_files]\n";
+        return -1;
+    }
+    bool success = true;
+    for (auto i : specFileNames) {
+        if (!systemSpecification.readSpecFile(i)) {
+            success = false;
+        }
+    }
+    if (success) {
+        success = systemSpecification.generateFiles(versionOfTestFiles);
+    }
+    return success ? 0 : -2;
+}