README.txt
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 3 described at: 4 http://www.chromium.org/developers/design-documents/extensions/proposed-changes/apis-under-development 5 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 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 (a] chromium.org) before you decide 10 which approach is better suited to your API. 11 12 The following steps suppose you're writing an experimental API called "Foo". 13 14 -------------------------------------------------------------------------------- 15 APPROACH 1: JSON FILES 16 17 1) Write your API specification. 18 Create "chrome/common/extensions/api/experimental_foo.json". For inspiration 19 look at the "app" API. Include descriptions fields to generate the 20 documentation. 21 22 2) Add your API specification to api.gyp. 23 Add "experimental_foo.json" to the "schema_files" section in 24 "chrome/common/extensions/api/api.gyp". 25 26 3) Write the API function handlers. 27 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You 28 should use the JSON Schema Compiler. Look at the "permissions_api.cc" for 29 details on how to do that. 30 31 -------------------------------------------------------------------------------- 32 APPROACH 2: IDL FILES 33 34 1) Write your API specification. 35 Create "chrome/common/extensions/api/experimental_foo.idl". For inspiration look 36 at "alarms.idl". Include comments, they will be used to automatically generate 37 the documentation. 38 39 2) Add your API specification to api.gyp. 40 Add "experimental_foo.idl" to the "schema_files" section in 41 "chrome/common/extensions/api/api.gyp". 42 43 3) Write the API function handlers. 44 Create foo_api.cc and foo_api.h under "chrome/browser/extensions/api/foo". You 45 should use the JSON Schema Compiler. Look at the "alarms_api.cc" for details on 46 how to do that. 47 48 -------------------------------------------------------------------------------- 49 STEPS COMMON TO BOTH APPROACHES 50 51 6) Write support classes for your API 52 If your API needs any support classes add them to 53 "chrome/browser/extensions/api/foo". Some old APIs added their support classes 54 directly to chrome/browser/extensions. Don't do that. 55 56 7) Update the project with your new files. 57 The files you created in (3) and (5) should be added to 58 "chrome/chrome_browser_extensions.gypi". 59 60 -------------------------------------------------------------------------------- 61 GENERATING DOCUMENTATION 62 63 8) Add a stub template in ../docs/templates/public corresponding to your API. 64 See other templates for inspiration. 65 66 9) Run ../docs/templates/server2/preview.py to view the generated documentation. 67 68 -------------------------------------------------------------------------------- 69 WRITING TESTS 70 71 12) Write a unit test for your API. 72 Create "chrome/browser/extensions/api/foo/foo_api_unittest.cc" and test each of 73 your API methods. See "alarms_api_unittest.cc" for details. Once done add your 74 .cc to "chrome/chrome_tests.gypi". 75
