Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(104)

Side by Side Diff: chrome/browser/extensions/api/README.txt

Issue 11747025: Run the JSON Schema Compiler's bundle compilation on JSON files. Previously it (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src
Patch Set: fix ms release build Created 7 years, 11 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
OLDNEW
1 This file describes steps and files needed when adding a new API to Chrome. 1 This file describes steps and files needed when adding a new API to Chrome.
2 Before you start coding your new API, though, make sure you follow the process 2 Before you start coding your new API, though, make sure you follow the process
3 described at: 3 described at:
4 http://www.chromium.org/developers/design-documents/extensions/proposed-change s/apis-under-development 4 http://www.chromium.org/developers/design-documents/extensions/proposed-change s/apis-under-development
5 5
6 Two approaches are available for writing your API specification. The original 6 Two approaches are available for writing your API specification. The original
7 approach relies on JSON specification files. The more recent and simpler system 7 approach relies on JSON specification files. The more recent and simpler system
8 uses Web IDL files, but does not yet support all the features of the JSON files. 8 uses Web IDL files, but does not yet support all the features of the JSON files.
9 Discuss with a member of the extensions team (aa@chromium.org) before you decide 9 Discuss with a member of the extensions team (aa@chromium.org) before you decide
10 which approach is better suited to your API. 10 which approach is better suited to your API.
11 11
12 The following steps suppose you're writing an experimental API called "Foo". 12 The following steps suppose you're writing an experimental API called "Foo".
13 13
14 -------------------------------------------------------------------------------- 14 --------------------------------------------------------------------------------
15 APPROACH 1: JSON FILES 15 APPROACH 1: JSON FILES
16 16
17 1) Write your API specification. 17 1) Write your API specification.
18 Create "chrome/common/extensions/api/experimental_foo.json". For inspiration 18 Create "chrome/common/extensions/api/experimental_foo.json". For inspiration
19 look at the "app" API. Include descriptions fields to generate the 19 look at the "app" API. Include descriptions fields to generate the
20 documentation. 20 documentation.
21 21
22 2) Add your API specification to extensions_api_resources.grd. 22 2) Add your API specification to api.gyp.
23 Add an "<include ...>" line with your JSON specification file to 23 Add "experimental_foo.json" to the "schema_files" section in
24 "chrome/common/extensions_api_resources.grd".
25
26 3) Add your API specification to api.gyp.
27 Add "experimental_foo.json" to the "json_schema_files" section in
28 "chrome/common/extensions/api/api.gyp". 24 "chrome/common/extensions/api/api.gyp".
29 25
30 4) Write the API function handlers. 26 3) Write the API function handlers.
31 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You 27 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You
32 should use the JSON Schema Compiler. Look at the "permissions_api.cc" for 28 should use the JSON Schema Compiler. Look at the "permissions_api.cc" for
33 details on how to do that. 29 details on how to do that.
34 30
35 5) Register function handlers.
36 In "chrome/browser/extensions/extension_function_registry.cc" include foo_api.h
37 and instantiate a RegisterFunction for each function you created in (3).
38
39 -------------------------------------------------------------------------------- 31 --------------------------------------------------------------------------------
40 APPROACH 2: IDL FILES 32 APPROACH 2: IDL FILES
41 33
42 1) Write your API specification. 34 1) Write your API specification.
43 Create "chrome/common/extensions/api/experimental_foo.idl". For inspiration look 35 Create "chrome/common/extensions/api/experimental_foo.idl". For inspiration look
44 at "alarms.idl". Include comments, they will be used to automatically generate 36 at "alarms.idl". Include comments, they will be used to automatically generate
45 the documentation. 37 the documentation.
46 38
47 2) Add your API specification to api.gyp. 39 2) Add your API specification to api.gyp.
48 Add "experimental_foo.idl" to the "idl_schema_files" section in 40 Add "experimental_foo.idl" to the "schema_files" section in
49 "chrome/common/extensions/api/api.gyp". 41 "chrome/common/extensions/api/api.gyp".
50 42
51 3) Write the API function handlers. 43 3) Write the API function handlers.
52 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You 44 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You
53 should use the JSON Schema Compiler. Look at the "alarms_api.cc" for details on 45 should use the JSON Schema Compiler. Look at the "alarms_api.cc" for details on
54 how to do that. 46 how to do that.
55 47
56 4-5) Nothing to do! Function handlers are automatically registered for you.
57
58 -------------------------------------------------------------------------------- 48 --------------------------------------------------------------------------------
59 STEPS COMMON TO BOTH APPROACHES 49 STEPS COMMON TO BOTH APPROACHES
60 50
61 6) Write support classes for your API 51 6) Write support classes for your API
62 If your API needs any support classes add them to 52 If your API needs any support classes add them to
63 "chrome/browser/extensions/api/foo". Some old APIs added their support classes 53 "chrome/browser/extensions/api/foo". Some old APIs added their support classes
64 directly to chrome/browser/extensions. Don't do that. 54 directly to chrome/browser/extensions. Don't do that.
65 55
66 7) Update the project with your new files. 56 7) Update the project with your new files.
67 The files you created in (3) and (5) should be added to 57 The files you created in (3) and (5) should be added to
68 "chrome/chrome_browser_extensions.gypi". 58 "chrome/chrome_browser_extensions.gypi".
69 59
70 -------------------------------------------------------------------------------- 60 --------------------------------------------------------------------------------
71 GENERATING DOCUMENTATION 61 GENERATING DOCUMENTATION
72 62
73 8) Build the project. (Only required if you used IDL files.) 63 8) Add a stub template in ../docs/templates/public corresponding to your API.
74 If you used IDL files, you need to build the project once in order for the 64 See other templates for inspiration.
75 documentation to be properly generated. Do this now. (This is required in order
76 to generate the JSON file used to generate documentation.)
77 65
78 9) Add your JSON file to the documentation controller 66 9) Run ../docs/templates/server2/preview.py to view the generated documentation.
79 Open "chrome/common/extensions/docs/js/api_page_generator.js" and add a line
80 referring to "../api/experimental_foo.json". Do this even if you used the IDL
81 approach as this JSON file has been generated in (7).
82
83 10) Write the static HTML page.
84 Write a small snippet of static HTML describing your API in
85 "chrome/common/extensions/docs/static/experimental.foo.html". For the moment,
86 just include the following in this file, adjusting it to describe your API:
87
88 <div id="pageData-name" class="pageData">Experimental Foo APIs</div>
89
90 <!-- BEGIN AUTHORED CONTENT -->
91 <p>The current methods allow applications to...</p>
92 <!-- END AUTHORED CONTENT -->
93
94 11) Build the documentation.
95 You will need to build DumpRenderTree once before you can build the
96 documentation. Once this is done, from "chrome/common/extensions/docs" run
97 "build/build.py". For more information on building documentation see README.txt
98 in "chrome/common/extensions/docs".
99 67
100 -------------------------------------------------------------------------------- 68 --------------------------------------------------------------------------------
101 WRITING TESTS 69 WRITING TESTS
102 70
103 12) Write a unit test for your API. 71 12) Write a unit test for your API.
104 Create "chrome/browser/extensions/api/foo/foo_api_unittest.cc" and test each of 72 Create "chrome/browser/extensions/api/foo/foo_api_unittest.cc" and test each of
105 your API methods. See "alarms_api_unittest.cc" for details. Once done add your 73 your API methods. See "alarms_api_unittest.cc" for details. Once done add your
106 .cc to "chrome/chrome_tests.gypi". 74 .cc to "chrome/chrome_tests.gypi".
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698