2011-11-29  Kentaro Hara  <haraken@chromium.org>

        Use the [Supplemental] IDL for webaudio attributes in Chromium

        https://bugs.webkit.org/show_bug.cgi?id=73394

        Reviewed by Adam Barth.

        - Overview: Using the [Supplemental] IDL, this patch moves the attribute

        declarations of webaudio from DOMWindow.idl into a new IDL file

        webaudio/DOMWindowWebAudio.idl, which helps make webaudio a self-contained

        feature (aka a module).

        - This patch changes the build flow of WebCore.gyp as follows:

            Previous build flow:

                foreach $idl (all IDL files) {

                    generate-bindings.pl depends on $idl;

                    generate-bindings.pl reads $idl;

                    generate-bindings.pl generates .h and .cpp files for $idl;

                }

            New build flow (See the discussions in bug 72138 for more details):

                resolve-supplemental.pl depends on all IDL files;

                resolve-supplemental.pl reads all IDL files;

                resolve-supplemental.pl resolves the dependency of [Supplemental=XXXX];

                resolve-supplemental.pl outputs supplemental_dependency.tmp;

                foreach $idl (all IDL files) {

                    generate-bindings.pl depends on $idl and supplemental_dependency.tmp;

                    generate-bindings.pl reads $idl;

                    generate-bindings.pl reads supplemental_dependency.tmp;

                    generate-bindings.pl generates .h and .cpp files for $idl, including all attributes in IDL files whilementing $idl;

                }

        - This patch introduces a temporary IDL, [Supplemented]. The [Supplemented] IDL

        will be removed after build scripts for all platforms support the [Supplemental] IDL.

        The motivation for the [Supplemented] IDL is as follows:

        In order to support the [Supplemental] IDL, we need to

        (1) run resolve-supplemental.pl and generate supplemental_dependency.tmp

        (2) and run generate-bindings.pl with the supplemental_dependency.tmp.

        This build flow requires a change on the following build scripts,

        but changing all the build scripts all at once without any regression is too difficult:

            - DerivedSources.make

            - DerivedSources.pri

            - GNUmakefile.am

            - PlatformBlackBerry.cmake

            - UseJSC.cmake

            - UseV8.cmake

            - WebCore.vcproj/MigrateScripts

            - WebCore.vcproj/WebCore.vcproj

            - bindings/gobject/GNUmakefile.am

            - WebCore.gyp/WebCore.gyp

        Thus, we are planning to change the build scripts one by one, which implies that

        we need to allow the temporary state in which some build scripts support [Supplemental] IDL

        but others do not. To accomplish this, we introduce a temporary IDL, [Supplemented].

        The [Supplemented] IDL on an attribute means that the attribute is marked with [Supplemental]

        in another IDL file somewhere, like this:

            DOMWindowWebAudio.idl:

                interface [

                    Supplemental=DOMWindow

                ] DOMWindowWebAudio {

                    attribute attr1;

                    attribute attr2;

                };

            DOMWindow.idl:

                interface [

                ] DOMWindow {

                    attribute [Supplemented] attr1; // This line will be removed after all build scripts support the [Su IDL

                    attribute [Supplemented] attr2; // This line will be removed after all build scripts support the [Su IDL.

                    attribute attr3;

                    attribute attr4;

                };

        Assuming these IDL files, this patch implements the following logic in generate-bindings.pl:

            - If a given build script supports the [Supplemental] IDL,

            generate-bindings.pl ignores all attributes with the [Supplemented] IDL.

            - Otherwise, generate-bindings.pl treats all attributes with the [Supplemented] IDL

            as normal attributes and instead ignores all attributes with the [Supplemental] IDL

            (i.e. generate-bindings.pl generates nothing from the IDL file with the [Supplemental] IDL).

        Tests: webaudio/*

        * WebCore.gyp/WebCore.gyp: Describes the build flow that I described above.

        * WebCore.gyp/scripts/action_derivedsourcesallinone.py:

        (main): Reads the IDL file names from the input file (i.e. supplemental_dependency.tmp), which are described at the first column of each line in the input file.

        * WebCore.gypi: Added DOMWindowWebAudio.idl.

        * bindings/scripts/generate-bindings.pl: As a temporary solution, if the platform does not support the [Supplemental] IDL, the perl script ignores the [Supplemental] IDL and instead uses the [Supplemented] IDL. Otherwise, the perl script ignores the [Supplemented] IDL and instead uses the [Supplemental] IDL.

        * page/DOMWindow.idl: Added the [Supplemented] IDL to webaudio-related attributes. As I described above, the [Supplemented] IDL will be removed after all platforms support the [Supplemental] IDL.

        * webaudio/DOMWindowWebAudio.idl: Added. Describes the [Supplemental=DOMWindow] IDL. The attributes in this IDL file should be treated as if they are written in DOMWindow.idl.

      'target_name': 'generate_supplemental_dependency',

      'type': 'none',

      'actions': [

         {

          'action_name': 'generateSupplementalDependency',

          'variables': {

            # Write sources into a file, so that the action command line won't

            # exceed OS limits.

            'idl_files_list': '<|(idl_files_list.tmp <@(bindings_idl_files))',

          },

          'inputs': [

            '../bindings/scripts/resolve-supplemental.pl',

            '../bindings/scripts/IDLParser.pm',

            '<(idl_files_list)',

            '<!@(cat <(idl_files_list))',

          ],

          'outputs': [

            '<(SHARED_INTERMEDIATE_DIR)/supplemental_dependency.tmp',

          ],

          'action': [

            'perl',

            '-w',

            '-I../bindings/scripts',

            '../bindings/scripts/resolve-supplemental.pl',

            '--defines',

            '<(feature_defines) LANGUAGE_JAVASCRIPT V8_BINDING',

            '--idlFilesList',

            '<(idl_files_list)',

            '--supplementalDependencyFile',

            '<(SHARED_INTERMEDIATE_DIR)/supplemental_dependency.tmp',

          ],

          'message': 'Resolving [Supplemental=XXX] dependencies in all IDL files',

        }

      ]

    },

    {

      'dependencies': [

        'generate_supplemental_dependency',

      ],

            '<(SHARED_INTERMEDIATE_DIR)/supplemental_dependency.tmp',

            '--supplementalDependencyFile',

            '<(SHARED_INTERMEDIATE_DIR)/supplemental_dependency.tmp',

            'webaudio/DOMWindowWebAudio.idl',

# FIXME(haraken): Remove this if-else statement.

# This if-else statement is temporary and will be removed

# after build scripts for all platforms support [Supplemental] IDL.

# The motivation for the [Supplemented] IDL is as follows:

#

# In order to support the [Supplemental] IDL, we need to

# (1) run resolve-supplemental.pl and generate supplemental_dependency.tmp

# (2) and run generate-bindings.pl with the supplemental_dependency.tmp.

#

# This build flow requires a change on the following build scripts,

# but changing all the build scripts all at once without any regression is too difficult:

#

#     - DerivedSources.make

#     - DerivedSources.pri

#     - GNUmakefile.am

#     - PlatformBlackBerry.cmake

#     - UseJSC.cmake

#     - UseV8.cmake

#     - WebCore.vcproj/MigrateScripts

#     - WebCore.vcproj/WebCore.vcproj

#     - bindings/gobject/GNUmakefile.am

#     - WebCore.gyp/WebCore.gyp

#

# Thus, we are planning to change the build scripts one by one, which implies that

# we need to allow the temporary state in which some build scripts support [Supplemental] IDL

# but others do not. To accomplish this, we introduce a temporal IDL, [Supplemented].

# The [Supplemented] IDL on an attribute means that the attribute is marked with [Supplemental]

# in another IDL file somewhere, like this:

#

# DOMWindowWebAudio.idl:

#     interface [

#         Supplemental=DOMWindow

#     ] DOMWindowWebAudio {

#         attribute attr1;

#         attribute attr2;

#     };

#

# DOMWindow.idl:

#     interface [

#     ] DOMWindow {

#         attribute [Supplemented] attr1; // This line will be removed after all build scripts support the [SupplementalL.

#         attribute [Supplemented] attr2; // This line will be removed after all build scripts support the [SupplementalL.

#         attribute attr3;

#         attribute attr4;

#     };

#

# Assuming these IDL files, the below code is doing the following logic:

#

#     - If a given build script supports the [Supplemental] IDL (i.e. --supplementalDependencyFile is specified),

#       we ignore all attributes with the [Supplemented] IDL.

#     - Otherwise (i.e. --supplementalDependencyFile is not specified),

#       we treat all attributes with the [Supplemented] IDL as normal attributes

#       and instead ignore all attributes with the [Supplemental] IDL

#       (i.e. we generate nothing from the idl file with the [Supplemental] IDL).

if ($supplementalDependencyFile) {

    foreach my $dataNode (@{$targetDocument->classes}) {

        my @nonSupplementedAttributes;

        foreach my $attribute (@{$dataNode->attributes}) {

            if (!$attribute->signature->extendedAttributes->{"Supplemented"}) {

                push(@nonSupplementedAttributes, $attribute);

            }

        }

        $dataNode->attributes(\@nonSupplementedAttributes);

    }

} else {

    foreach my $dataNode (@{$targetDocument->classes}) {

        if ($dataNode->extendedAttributes->{"Supplemental"}) {

            exit 0;

        }

    }

}

# Temporary if-else statement until here.

/*

 * Copyright (C) 2011 Google Inc. All rights reserved.

 *

 * This library is free software; you can redistribute it and/or

 * modify it under the terms of the GNU Library General Public

 * License as published by the Free Software Foundation; either

 * version 2 of the License, or (at your option) any later version.

 *

 * This library 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

 * Library General Public License for more details.

 *

 * You should have received a copy of the GNU Library General Public License

 * along with this library; see the file COPYING.LIB.  If not, write to

 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,

 * Boston, MA 02110-1301, USA.

 */

module window {

    interface [

        Conditional=WEB_AUDIO,

        Supplemental=DOMWindow

    ] DOMWindowWebAudio {

        attribute [JSCCustomGetter, EnabledAtRuntime] AudioContextConstructor webkitAudioContext;

        attribute AudioPannerNodeConstructor webkitAudioPannerNode;

        attribute AudioProcessingEventConstructor AudioProcessingEvent;

        attribute OfflineAudioCompletionEventConstructor OfflineAudioCompletionEvent;

    };

}