diff --git a/pdk/docs/about/philosophy.jd b/pdk/docs/about/philosophy.jd index a1a75ccba..64d04234e 100644 --- a/pdk/docs/about/philosophy.jd +++ b/pdk/docs/about/philosophy.jd @@ -1,7 +1,6 @@ page.title=Philosophy and Goals doc.type=about @jd:body -

Android is an open-source software stack for mobile phones and similar devices. The Android Open Source Project is tasked with maintaining current and developing new versions of the Android software. We believe that users @@ -77,4 +76,3 @@ we ship high-quality, flagship devices with an intense product and end-user focus. The "next release" of Android is driven by the product needs for the next generation of mobile devices; the resulting excellent product is then released to open source and becomes the new current version of the platform.

-
diff --git a/pdk/docs/community/groups-charter.jd b/pdk/docs/community/groups-charter.jd index 69381d9a9..6d5b501ed 100644 --- a/pdk/docs/community/groups-charter.jd +++ b/pdk/docs/community/groups-charter.jd @@ -1,24 +1,6 @@ page.title=Android Discussion Groups Charter doc.type=community @jd:body -

Android mailing lists charter -

-

Contents -

-
  1. 1 -Audience -
    2. -
  2. 2 -Mailing list rules -
    3. -
  3. 3 -Contacting the moderators -
    4. -
-
-
-
-

Audience

@@ -47,4 +29,3 @@ Contacting the moderators

But if you see an outrageous violation, want to report spam, feel very strongly about something, or even if you just want to chat, then contact the mailing list's owners. It's what we're here for!

-
diff --git a/pdk/docs/community/index.jd b/pdk/docs/community/index.jd index d00838fbc..5d219c8bd 100644 --- a/pdk/docs/community/index.jd +++ b/pdk/docs/community/index.jd @@ -34,21 +34,23 @@ href="http://developer.android.com/community/index.html">http://developer.androi read How To Ask Questions The Smart Way. +

Open Source Project discussions

Using email with Google Groups

diff --git a/pdk/docs/compatibility/contact-us.jd b/pdk/docs/compatibility/contact-us.jd index 92062ba70..432dc2296 100644 --- a/pdk/docs/compatibility/contact-us.jd +++ b/pdk/docs/compatibility/contact-us.jd @@ -1,11 +1,10 @@ -page.title=Android Compatibility - Contact Us +page.title=Contact Us doc.type=compatibility @jd:body -

Mailing list -

+

Mailing list

Welcome to the Android compatibility mailing list!
To get the most out of the mailing list discussions, please do the following before you post: -
  1. Read themailing list charter +
    1. Read the mailing list charter that covers the community guidelines.

    2. Search the mailing list archives @@ -13,15 +12,15 @@ to see whether your questions have already been discussed.

    3. Be very clear about your question in the subject -- it helps everyone, both those trying to answer your question as well as those who may be looking for information in the future.

    4. Give plenty of details -in your post to help others understand your problem. Code or log snippets, as well as pointers to screenshots, may also be helpful. For a great guide to phrasing your questions, readHow To Ask Questions The Smart Way +in your post to help others understand your problem. Code or log snippets, as well as pointers to screenshots, may also be helpful. For a great guide to phrasing your questions, read How To Ask Questions The Smart Way .

    There are two ways to join the Android compatibility mailing list:
-
  • Once all the tests are executed, you can view the test results in your browser and use the results to adjust your design. You can continue to run the CTS throughout your development process.
    • -
  • If you see test failures, follow the instructions on theCompatibility FAQ +
  • If you see test failures, follow the instructions on the Compatibility FAQ page.
    • When you are ready, you can submit the report generated by the CTS to cts@android.com. The report is a .zip archived file that contains XML results and supplemental information such as screen captures.
    @@ -50,15 +40,15 @@ The CTS includes the following types of test cases:

    Areas Covered

    -The unit test cases cover the following areas to ensure compatibility
    +The unit test cases cover the following areas to ensure compatibility
    - + - - - + - + - - +
    AreaDescription
    AreaDescription
    Signature tests For each Android release, there are XML files describing the signatures of all public APIs contained in the release. The CTS contains a utility to check those API signatures against the APIs available on the device. The results from signature checking are recorded in the test result XML file.
    Platform API TestsTest the platform (core libraries and Android Application Framework) APIs as documented in the SDKClass Index +Test the platform (core libraries and Android Application Framework) APIs as documented in the SDK Class Index to ensure API correctness:
    • correct class, attribute and method signatures
      • @@ -68,7 +58,7 @@ to ensure API correctness:
    Dalvik VM TestsThe tests focus on testing the Dalvik VM
    Platform Data ModelThe CTS tests the core platform data model as exposed to application developers through content providers, as documented in the SDKandroid.provider +The CTS tests the core platform data model as exposed to application developers through content providers, as documented in the SDK android.provider package:
    • contacts
      • @@ -78,13 +68,13 @@ package:
    Platform IntentsThe CTS tests the core platform intents, as documented in the SDKAvailable Intents.The CTS tests the core platform intents, as documented in the SDK Available Intents.
    Platform PermissionsThe CTS tests the core platform permissions, as documented in the SDKAvailable Permissions.The CTS tests the core platform permissions, as documented in the SDK Available Permissions.
    Platform Resources
    		The CTS tests for correct handling of the core platform resource types, as documented in the SDKAvailable Resource Types +
    Platform Resources
    		The CTS tests for correct handling of the core platform resource types, as documented in the SDK Available Resource Types . This includes tests for:
    • simple values
      • diff --git a/pdk/docs/compatibility/faq.jd b/pdk/docs/compatibility/faq.jd index 71a193d74..1eafeea47 100644 --- a/pdk/docs/compatibility/faq.jd +++ b/pdk/docs/compatibility/faq.jd @@ -1,41 +1,17 @@ -page.title=Android Compatibility - Frequently Asked Questions +page.title=Frequently Asked Questions doc.type=compatibility @jd:body -

      Compatibility FAQ

      -

      The CTS report shows test failures -- what should I do now?

      Step 1: Get the latest CTS version. -Make sure you are running the latest version of CTS -- check if your version is the same as the one posted on theDownloads +Make sure you are running the latest version of CTS -- check if your version is the same as the one posted on the Downloads page. If not, make sure you update to the latest version and re-run CTS. As we find issues in CTS, we push out new versions with fixes to the tests and/or frame-work. Using the latest version minimizes the chances of you facing any CTS specific issues.

      Step 2: Investigate the CTS source code. -Make sure you have grabbed the CTS sources provided on theDownload +Make sure you have grabbed the CTS sources provided on the Download page. Then unzip the CTS report zip$CTS_ROOT/repository/results/start time.zipand opentestResult.xmlin your favorite browser. Find the exception next to the failing test and check the corresponding source file for possible failure causes.

      Step 3: Fix the error in your source and re-run CTS. @@ -54,7 +30,7 @@ Android 1.5 CTS r1 known issues

      The following tests have known issues with non en_US locales:
      -
      tests.api.java.io.PrintStreamTest#test_formatLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object
      tests.api.java.io.PrintStreamTest#test_printfLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object
      tests.api.java.io.PrintWriterTest#test_formatLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object
      tests.api.java.io.PrintWriterTest#test_printfLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object
      tests.api.java.util.CalendarTest#test_hashCode
      tests.api.java.util.CalendarTest#test_getFirstDayOfWeek
      tests.api.java.util.CalendarTest#test_getInstanceLjava_util_Locale
      tests.api.java.util.CalendarTest#test_getInstanceLjava_util_TimeZoneLjava_util_Locale
      tests.api.java.util.CalendarTest#test_getMinimalDaysInFirstWeek
      tests.api.java.util.FormatterTest#test_formatLjava_lang_String$Ljava_lang_Object_ByteShortIntegerLongConversionD
      tests.api.java.util.FormatterTest#test_formatLjava_lang_String$Ljava_lang_Object_DateTimeConversion
      tests.api.java.util.FormatterTest#test_formatLjava_lang_String$LBigInteger
      tests.api.java.util.FormatterTest#test_formatLjava_lang_String$Ljava_lang_Object_BigIntegerPaddingConversion
      tests.api.java.util.FormatterTest#test_formatLjava_util_LocaleLjava_lang_StringLjava_lang_Object
      tests.api.java.util.GregorianCalendarTest#test_ConstructorLjava_util_Locale
      tests.api.java.util.LocaleTest#test_getDisplayCountryLjava_util_Locale
      tests.api.java.util.LocaleTest#test_getDisplayLanguageLjava_util_Locale
      tests.api.java.util.LocaleTest#test_getDisplayNameLjava_util_Locale
      tests.api.java.util.ScannerTest#test_nextDouble
      tests.api.java.util.ScannerTest#test_nextFloat
      tests.api.java.util.ScannerTest#test_nextInt
      tests.api.java.util.ScannerTest#test_nextIntI
      tests.api.java.util.ScannerTest#test_nextLong
      tests.api.java.util.ScannerTest#test_nextShortI
      tests.api.java.util.ScannerTest#test_nextShort
      tests.api.java.util.ScannerTest#test_nextLongI
      tests.api.java.util.ScannerTest#test_hasNextIntI
      tests.api.java.util.ScannerTest#test_hasNextInt
      tests.api.java.util.ScannerTest#test_hasNextFloat
      tests.api.java.util.ScannerTest#test_hasNextShortI
      tests.api.java.util.ScannerTest#test_hasNextShort
      tests.api.java.util.ScannerTest#test_hasNextLongI
      tests.api.java.util.ScannerTest#test_hasNextLong
      tests.api.java.util.ScannerTest#test_hasNextDouble
      tests.api.java.util.ScannerTest#test_hasNextBigDecimal
      tests.api.java.util.ScannerTest#test_nextBigDecimal
      tests.api.java.util.TimeZoneTest#test_getDisplayNameLjava_util_Locale
      tests.api.java.util.TimeZoneTest#test_getDisplayNameZILjava_util_Locale
      org.apache.harmony.text.tests.java.text.DateFormatTest#test_getAvailableLocales
      org.apache.harmony.text.tests.java.text.DecimalFormatSymbolsTest#test_getCurrency
      org.apache.harmony.text.tests.java.text.DecimalFormatTest#test_formatToCharacterIteratorLjava_lang_Object
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getInstanceLjava_util_Locale
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_parseObjectLjava_lang_StringLjava_text_ParsePosition
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getIntegerInstanceLjava_util_Locale
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_formatLdouble
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_formatLlong
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getCurrencyInstanceLjava_util_Locale
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getNumberInstanceLjava_util_Locale
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getPercentInstanceLjava_util_Locale
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_setGroupingUsed

      +
      tests.api.java.io.PrintStreamTest#test_formatLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object
      tests.api.java.io.PrintStreamTest#test_printfLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object
      tests.api.java.io.PrintWriterTest#test_formatLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object
      tests.api.java.io.PrintWriterTest#test_printfLjava_util_Locale_Ljava_lang_String_$Ljava_lang_Object
      tests.api.java.util.CalendarTest#test_hashCode
      tests.api.java.util.CalendarTest#test_getFirstDayOfWeek
      tests.api.java.util.CalendarTest#test_getInstanceLjava_util_Locale
      tests.api.java.util.CalendarTest#test_getInstanceLjava_util_TimeZoneLjava_util_Locale
      tests.api.java.util.CalendarTest#test_getMinimalDaysInFirstWeek
      tests.api.java.util.FormatterTest#test_formatLjava_lang_String$Ljava_lang_Object_ByteShortIntegerLongConversionD
      tests.api.java.util.FormatterTest#test_formatLjava_lang_String$Ljava_lang_Object_DateTimeConversion
      tests.api.java.util.FormatterTest#test_formatLjava_lang_String$LBigInteger
      tests.api.java.util.FormatterTest#test_formatLjava_lang_String$Ljava_lang_Object_BigIntegerPaddingConversion
      tests.api.java.util.FormatterTest#test_formatLjava_util_LocaleLjava_lang_StringLjava_lang_Object
      tests.api.java.util.GregorianCalendarTest#test_ConstructorLjava_util_Locale
      tests.api.java.util.LocaleTest#test_getDisplayCountryLjava_util_Locale
      tests.api.java.util.LocaleTest#test_getDisplayLanguageLjava_util_Locale
      tests.api.java.util.LocaleTest#test_getDisplayNameLjava_util_Locale
      tests.api.java.util.ScannerTest#test_nextDouble
      tests.api.java.util.ScannerTest#test_nextFloat
      tests.api.java.util.ScannerTest#test_nextInt
      tests.api.java.util.ScannerTest#test_nextIntI
      tests.api.java.util.ScannerTest#test_nextLong
      tests.api.java.util.ScannerTest#test_nextShortI
      tests.api.java.util.ScannerTest#test_nextShort
      tests.api.java.util.ScannerTest#test_nextLongI
      tests.api.java.util.ScannerTest#test_hasNextIntI
      tests.api.java.util.ScannerTest#test_hasNextInt
      tests.api.java.util.ScannerTest#test_hasNextFloat
      tests.api.java.util.ScannerTest#test_hasNextShortI
      tests.api.java.util.ScannerTest#test_hasNextShort
      tests.api.java.util.ScannerTest#test_hasNextLongI
      tests.api.java.util.ScannerTest#test_hasNextLong
      tests.api.java.util.ScannerTest#test_hasNextDouble
      tests.api.java.util.ScannerTest#test_hasNextBigDecimal
      tests.api.java.util.ScannerTest#test_nextBigDecimal
      tests.api.java.util.TimeZoneTest#test_getDisplayNameLjava_util_Locale
      tests.api.java.util.TimeZoneTest#test_getDisplayNameZILjava_util_Locale
      org.apache.harmony.text.tests.java.text.DateFormatTest#test_getAvailableLocales
      org.apache.harmony.text.tests.java.text.DecimalFormatSymbolsTest#test_getCurrency
      org.apache.harmony.text.tests.java.text.DecimalFormatTest#test_formatToCharacterIteratorLjava_lang_Object
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getInstanceLjava_util_Locale
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_parseObjectLjava_lang_StringLjava_text_ParsePosition
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getIntegerInstanceLjava_util_Locale
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_formatLdouble
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_formatLlong
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getCurrencyInstanceLjava_util_Locale
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getNumberInstanceLjava_util_Locale
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_getPercentInstanceLjava_util_Locale
      org.apache.harmony.text.tests.java.text.NumberFormatTest#test_setGroupingUsed


      Can I remove the 'final' modifier from classes in the Android public APIs and still be an Android-compatible device? @@ -107,18 +83,18 @@ I see a failure in my report with the comment "A test that was a known failure a

      Why are compass and accelerometer required for Android compatibility?

      -
      Whenever possible, we try to open up hardware options by making the Android software smarter.For example, in Android 1.5 we added an Input Method Framework and soft keyboard so that devices didn't need physical text input devices.The AndroidDonut +
      Whenever possible, we try to open up hardware options by making the Android software smarter.For example, in Android 1.5 we added an Input Method Framework and soft keyboard so that devices didn't need physical text input devices.The Android Donut release will the ability to scale application windows to different densities and resolutions so that devices aren't restricted to 160-180dpi HVGA displays.

      Unfortunately, software can only do so much, and a compass and accelerometer are things Android cannot replace with software.These two input devices are now commonly used by applications.For example, many of the most popular applications in Android Market:

      -Google Sky Map -uses compass and accelerometer
      -Labyrinth +uses compass and accelerometer
      -      Labyrinth -uses accelerometer
      -Bonzai Blast +uses accelerometer
      -      Bonzai Blast -uses accelerometer
      -Wikitude +uses accelerometer
      -      Wikitude -uses compass and accelerometer
      -Zagat +uses compass and accelerometer
      -      Zagat -uses compass

      As Market has no way of knowing whether an application uses these controls, we would not be able to filter these out of Android Market for devices which don't have the required hardware.This would create a bad user experience and could hurt the Android ecosystem if developers can no longer rely on these features in handsets, or receive bad reviews from consumers who have devices which can't support the features.
      +uses compass

      As Market has no way of knowing whether an application uses these controls, we would not be able to filter these out of Android Market for devices which don't have the required hardware.This would create a bad user experience and could hurt the Android ecosystem if developers can no longer rely on these features in handsets, or receive bad reviews from consumers who have devices which can't support the features.

      diff --git a/pdk/docs/compatibility/index.jd b/pdk/docs/compatibility/index.jd index 9f62872a0..0c39a9853 100644 --- a/pdk/docs/compatibility/index.jd +++ b/pdk/docs/compatibility/index.jd @@ -2,10 +2,16 @@ page.title=Android Compatibility doc.type=compatibility @jd:body

      Android is an open source product, and anyone can use the source code to build -devices. Incautious implementations, however, can easily introduce bugs that -cause third-party applications to break. The purpose of the Android -Compatibility Program is to help Android device implementations remain -compatible with all apps.

      +devices. The purpose of the Android compatibility program is to help Android +device implementations remain compatible with all apps.

      +

      A device is considered compatible if existing and new third-party +applications run correctly on it. Poor device implementations that change APIs +or alter behaviors will break these apps and so are not compatible. The +Android compatibility program's aim is to ensure that these APIs are +consistently implemented across devices.

      +

      The latest version of the Android source code and compatibility program is +1.6, which roughly corresponded to the Donut branch. The compatibility +program for Android 2.x (corresponding to Eclair) is coming soon.

      Why build compatible Android devices?

      Users want a customizable device.

      A mobile phone is a highly personal, always-on, always-present gateway to @@ -41,7 +47,8 @@ href="{@docRoot}compatibility/overview.html">the program overview.

      This document enumerates the software and the hardware features of a compatible Android device.

    • Pass the Compatibility Test Suite (CTS)

      You can use the CTS - as an ongoing aid to compatibility during the development process.

      • + (included in the Android source code) as an ongoing aid to compatibility + during the development process.

    • Submit CTS report

      [Optional] You can also submit your CTS report, so that it can be validated and recorded.

      Note: the submission system is currently under construciton, and is not currently diff --git a/pdk/docs/downloads/index.jd b/pdk/docs/downloads/index.jd index f196808e0..b6f5a2fa8 100644 --- a/pdk/docs/downloads/index.jd +++ b/pdk/docs/downloads/index.jd @@ -2,7 +2,6 @@ page.title=Downloads doc.type=downloads doc.hidenav=true @jd:body -

      This page provides access to various downloads. Note that if you're looking for the Android SDK (for application developers), you should visit developer.android.com.

      @@ -43,4 +42,3 @@ there is no compatibility program for Android 1.5 and earlier. Note also that there is no compatibility program for Android 2.0, since it was superceded by Android 2.1 after only a few weeks.

      -
      diff --git a/pdk/docs/images/code-lines.png b/pdk/docs/images/code-lines.png new file mode 100644 index 000000000..acfb77b4f Binary files /dev/null and b/pdk/docs/images/code-lines.png differ diff --git a/pdk/docs/porting/bluetooth.jd b/pdk/docs/porting/bluetooth.jd index e9749827b..ceb8683c7 100755 --- a/pdk/docs/porting/bluetooth.jd +++ b/pdk/docs/porting/bluetooth.jd @@ -170,7 +170,7 @@ sdptool records ADDRESS # request the SDP records of another BT device.

      Development Notes

        -
      • HID Support
        +
      • HID Support
        Cupcake features some early work—Bluez has an HID plugin, external/bluez/utils/input/Android.mk, which gets compiled.

        You can interact directly with this plugin using dbus-send and dbus-monitor. While not officially supported, you should be able to connect and use a HID keyboard and mouse using the Bluez HID plugin API. Next steps include plumbing the plugin API in the Android Java framework and offering better support for HID input methods (new keymaps and mouse support).
        diff --git a/pdk/docs/porting/bluetooth/bluetooth_process.jd b/pdk/docs/porting/bluetooth/bluetooth_process.jd index ea46f231e..00ec0daa1 100755 --- a/pdk/docs/porting/bluetooth/bluetooth_process.jd +++ b/pdk/docs/porting/bluetooth/bluetooth_process.jd @@ -1,6 +1,6 @@ page.title=Bluetooth Process Diagram pdk.version=1.0 -doc.type=guide +doc.type=porting @jd:body

        The diagram below offers a process-oriented architectural overview of Android's Bluetooth stack. Click Bluetooth to return to the Bluetooth overview page.

        diff --git a/pdk/docs/porting/bring_up.jd b/pdk/docs/porting/bring_up.jd index 022c18534..1d04b8602 100755 --- a/pdk/docs/porting/bring_up.jd +++ b/pdk/docs/porting/bring_up.jd @@ -264,7 +264,7 @@ runs a service. Options are described in the table below:

    Properties

    - Init updates some system properties to provide some insight into
    + Init updates some system properties to provide some insight into
    what it's doing:

    diff --git a/pdk/docs/porting/build_system.jd b/pdk/docs/porting/build_system.jd index e5811bd4f..686fba0d5 100755 --- a/pdk/docs/porting/build_system.jd +++ b/pdk/docs/porting/build_system.jd @@ -211,7 +211,7 @@ currently-defined build variants:
    - + diff --git a/pdk/docs/source/building-dream.jd b/pdk/docs/source/building-dream.jd index 71b4f5890..f5472ce4e 100644 --- a/pdk/docs/source/building-dream.jd +++ b/pdk/docs/source/building-dream.jd @@ -1,9 +1,12 @@ -page.title=Android Compatibility - Compatibility Test Suite +page.title=Building for ADP1 doc.type=source @jd:body -

    Building For Dream -

    -
    The basic manifest for cupcake (and above) defines which projects are needed to do a generic build for the emulator or for unlocked Dream devices (e.g. the Android Dev Phone 1). You need to have an appropriate device running a matching official image.

    To build donut or master for dream (your device needs to be an ADP1 running an official 1.6 system):
    1. Follow thenormal steps +
      The basic manifest for cupcake (and above) defines which projects are +needed to do a generic build for the emulator or for unlocked Dream devices +(e.g. the Android Dev Phone 1). You need to have an appropriate device running +a matching official image.

      To build donut or master for dream (your +device needs to be an ADP1 running an official 1.6 system):
      1. Follow +the normal steps to setup repo and check out the sources.
      2. At the root of your source tree, run ". build/envsetup.sh" like you normally would for an emulator build. @@ -17,7 +20,7 @@ to setup repo and check out the sources.
      3. from this point, the fastboot tool (which is put automatically in your path) can be used to flash a device: boot the device into the bootloader by holding the back key while pressing the power key, and run "fastboot -w flashall".
      -To build cupcake for dream (your device needs to be an ADP1 running an official 1.5 system):
      1. Follow thenormal steps +To build cupcake for dream (your device needs to be an ADP1 running an official 1.5 system):
        1. Follow the normal steps to setup repo and check out the sources.
        2. At the root of your source tree, run ". build/envsetup.sh" like you normally would for an emulator build. diff --git a/pdk/docs/source/cla-corporate.jd b/pdk/docs/source/cla-corporate.jd index 5ddfe6f0b..0f9452b80 100644 --- a/pdk/docs/source/cla-corporate.jd +++ b/pdk/docs/source/cla-corporate.jd @@ -1,13 +1,11 @@ -page.title=Android Compatibility - Compatibility Test Suite +page.title=Corporate Contributor License Agreement doc.type=source @jd:body -

          Corporate Contributor License Grant - Android Open Source Project -

          In order to clarify the intellectual property license granted with Contributions from any person or entity, the Android Open Source Project (the "Project") must have a Contributor License Grant ("Grant") on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for your protection as a Contributor as well as the protection of the Project and the Android Open Source Project Leads (the "Project Leads"); it does not change your rights to use your own Contributions for any other purpose.

          This version of the Grant allows an entity (the "Corporation") to submit Contributions to the Project Leads, to authorize Contributions submitted by its designated employees to the Project Leads, and to grant copyright and patent licenses thereto. If you have not already done so, please complete and send an original signed Grant to

          -
          Google Inc.
          Attn: Open Source Program Office
          1600 Amphitheatre Pkwy
          Building 43
          Mountain View, CA 94043
          U.S.A.
          +
          Google Inc.
          Attn: Open Source Program Office
          1600 Amphitheatre Pkwy
          Building 43
          Mountain View, CA 94043
          U.S.A.

          Scanned agreements may also be emailed in PDF form to cla-submissions@google.com

          If necessary, you may send it by facsimile to (650) 887-1625. Please read this document carefully before signing and keep a copy for your records. diff --git a/pdk/docs/source/cla-individual.jd b/pdk/docs/source/cla-individual.jd index 1433318b6..8890be87e 100644 --- a/pdk/docs/source/cla-individual.jd +++ b/pdk/docs/source/cla-individual.jd @@ -1,16 +1,14 @@ -page.title=Android Compatibility - Compatibility Test Suite +page.title=Contributor License Agreement for Individuals doc.type=source @jd:body -

          Individual Contributor License Grant - Android Open Source Project -

          -

          Please visit thecode review tool +

          Please visit the code review tool to execute the grant online.This page provides the text of the Individual Contributor License Grant for your quick review.


          In order to clarify the intellectual property license granted with Contributions from any person or entity, the Android Open Source Project (the "Project") must have a Contributor License Grant ("Grant") on file that has been signed by each Contributor, indicating agreement to the license terms below. This license is for your protection as a Contributor as well as the protection of the Project and the Android Open Source Project Leads (the "Project Leads"); it does not change your rights to use your own Contributions for any other purpose. If you have not already done so, please complete and send an original signed Grant to

          -
          Google Inc.
          Attn: Open Source Program Office
          1600 Amphitheatre Pkwy
          Building 43
          Mountain View, CA 94043
          U.S.A.
          -

          Scanned agreements may also be emailed in PDF form to cla-submissions@google.com, sent by facsimile to (650) 887-1625, orsigned electronically +

          Google Inc.
          Attn: Open Source Program Office
          1600 Amphitheatre Pkwy
          Building 43
          Mountain View, CA 94043
          U.S.A.
          +

          Scanned agreements may also be emailed in PDF form to cla-submissions@google.com, sent by facsimile to (650) 887-1625, or signed electronically .

          Please read this document carefully before signing and keep a copy for your records. diff --git a/pdk/docs/source/code-lines.jd b/pdk/docs/source/code-lines.jd new file mode 100644 index 000000000..61b400d5e --- /dev/null +++ b/pdk/docs/source/code-lines.jd @@ -0,0 +1,77 @@ +page.title=Android Code-Lines +doc.type=source +@jd:body +

          The Android Open Source Project maintains a complete software stack intended +to be ported by OEMs and other device implementors to run on actual hardware. +Accordingly, we maintain a number of "code lines" to clearly separate the +current stable version of Android from unstable experimental work.

          +

          The chart below depicts at a conceptual level how AOSP manages code and +releases. We're referring to these as "code lines" instead of "branches" +simply because at any given moment there may be more than one branch extant +for a given "code line". For instance, when a release is cut, sometimes that +will become a new branch in git, and sometimes not, based on the needs of the +moment.

          + +

          Notes and Explanations

          +
            +
          • A release corresponds to a formal version of the Android platform, such +as 1.5, 2.0, and so on. Generally speaking, a release of the platform +corresponds to a version of the SdkVersion field used in +AndroidManifest.xml files, and defined in frameworks/base/api in +the source tree.
            • +
          • An upstream project is an open-source project from which the Android +stack is pulling code. These include obvious projects such as the Linux kernel +and WebKit, but over time we are migrating some of the semi-autonomous +Android projects (such as Dalvik, the Android SDK tools, Bionic, and so on) to +work as "upstream" projects. These will be developed entirely in the public +tree, and snapshots will be periodically pulled into releases.
            • +
          • The diagram refers to "Eclair" and "Flan"; however, they are simply +placeholders, and the diagram actually reflects the overall release and +branching strategy.
            • +
          • At all times, the Release code-line (which may actually consist of +more than one actual branch in git) is considered the sole canonical source +code for a given Android platform. OEMs and other groups building devices +should pull only from a Release branch.
            • +
          • We will be setting up an "Experimental" code-line to capture changes from +the community, so that they can be iterated on, with an eye toward stability.
            • +
          • Changes that prove stable will eventually be pulled into a Release +branch. Note that this will only apply to bug fixes, app improvements, and +other things that do not affect the APIs of the platform.
            • +
          • Changes will be pulled into Release branches from upstream projects +(include the Android "upstream" projects) as necessary.
            • +
          • The "n+1"th version (that is, next major version of the framework and +platform APIs) will be developed by Google internally. (See below for +details.)
            • +
          • Changes will be pulled from upstream, Release, and Experimental branches +into Google's private branch as necessary.
            • +
          • When the platform APIs for the next version have stabilized and been fully +tested, Google will cut a release of the next platform version. (This +specifically refers to a new SdkVersion.) This will also +correspond to the internal code-line being made a public Release branch, and the +new current platform code-line.
            • +
          • When a new platform version is cut, a corresponding Experimental +code-line.
            • +
          +

          About Private Code-Lines

          +

          The source management strategy above includes a code-line that Google will +keep private. The reason for this is to focus attention on the current public +version of Android.

          +

          OEMs and other device builders naturally want to ship devices with the +latest version of Android. Similarly, application developers don't want to +deal with more extant platform versions than strictly necessary. Meanwhile, +Google retains responsibility for the strategic direction of Android as a +platform and a product. Our approach is based on focusing on a small number of +flagship devices to drive features, and secure protections of Android-related +intellectual property through patents and the like.

          +

          As a result, Google frequently has possession of confidential +information of third parties, and we must refrain from revealing patentable +features until we've secured the appropriate protections. Meanwhile, there are +real risks to the platform arising from having too many platform versions +extant at once. For these reasons, we have structured the open-source project +-- including third-party contributions -- to focus on the currently-public +stable version of Android. "Deep development" on the next version of the +platform will happen in private, until it's ready to become an official +release.

          +

          We recognize that many contributors will disagree with this approach. We +respect that others may have a different point of view; however, this is the +approach that we feel is best, and the one we've chosen to implement.

          diff --git a/pdk/docs/source/code-style.jd b/pdk/docs/source/code-style.jd index 540ac997e..3122ea88c 100644 --- a/pdk/docs/source/code-style.jd +++ b/pdk/docs/source/code-style.jd @@ -1,8 +1,6 @@ -page.title=Android Compatibility - Compatibility Test Suite +page.title=Code Style Guidelines for Contributors doc.type=source @jd:body -

          Code Style Guide -

          Android Code Style Rules

          The rules below are not guidelines or recommendations, but strict rules.You may not disregard the rules we list below @@ -29,12 +27,12 @@ except as approved on a need-to-use basis.

        Java Library Rules

        -

        There are conventions for using Android's Java libraries and tools. In some cases, the convention has changed in important ways and older code might use a deprecated pattern or library. When working with such code, it's okay to continue the existing style (seeConsistency +

        There are conventions for using Android's Java libraries and tools. In some cases, the convention has changed in important ways and older code might use a deprecated pattern or library. When working with such code, it's okay to continue the existing style (see Consistency ). When creating new components never use deprecated libraries.

        Java Style Rules

        -

        Programs are much easier to maintain when all files have a consistent style. We follow the standard Java coding style, as defined by Sun in theirCode Conventions for the Java Programming Language +

        Programs are much easier to maintain when all files have a consistent style. We follow the standard Java coding style, as defined by Sun in their Code Conventions for the Java Programming Language , with a few exceptions and additions. This style guide is comprehensive and detailed and is in common usage in the Java community.

        In addition, we enforce the following style rules: @@ -108,7 +106,7 @@ Sometimes it is tempting to write code that completely ignores an exception like 

        void setServerPort(String value) throws ConfigurationException {
        try {
        serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
        throw new ConfigurationException("Port " + value + " is not valid.");
        }

      2. Handle the error gracefully and substitute an appropriate value in the catch {} block. -
        /** Set port. If value is not a valid number, 80 is substituted. */
        void setServerPort(String value) {
        try {
        serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
        serverPort = 80;  // default port for server
        }
        +
        /** Set port. If value is not a valid number, 80 is substituted. */
        void setServerPort(String value) {
        try {
        serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
        serverPort = 80;  // default port for server 
        }
      3. Catch the Exception and throw a new RuntimeException. This is dangerous: only do it if you are positive that if this error occurs, the appropriate thing to do is crash. 
        /** Set port. If value is not a valid number, die. */
        void setServerPort(String value) {
        try {
        serverPort = Integer.parseInt(value);
        } catch (NumberFormatException e) {
        throw new RuntimeException("port " + value " is invalid, ", e);
        }
        @@ -120,7 +118,7 @@ Note that the original exception is passed to the constructor for RuntimeExcepti

        Exceptions: do not catch generic Exception

        Sometimes it is tempting to be lazy when catching exceptions and do something like this: -
        try {
        someComplicatedIOFunction();        // may throw IOException
        someComplicatedParsingFunction();   // may throw ParsingException
        someComplicatedSecurityFunction();  // may throw SecurityException
        // phew, made it all the way
        } catch (Exception e) {               // I'll just catch all exceptions
        handleError();                      // with one generic handler!
        }

        +
        try {
        someComplicatedIOFunction();        // may throw IOException 
        someComplicatedParsingFunction();   // may throw ParsingException 
        someComplicatedSecurityFunction();  // may throw SecurityException 
        // phew, made it all the way 
        } catch (Exception e) {               // I'll just catch all exceptions 
        handleError();                      // with one generic handler!
        }

        You should not do this. In almost all cases it is inappropriate to catch generic Exception or Throwable, preferably not Throwable, because it includes Error exceptions as well. It is very dangerous. It means that Exceptions you never expected (including RuntimeExceptions like ClassCastException) end up getting caught in application-level error handling. It obscures the failure handling properties of your code. It means if someone adds a new type of Exception in the code you're calling, the compiler won't help you realize you need to handle that error differently. And in most cases you shouldn't be handling different types of exception the same way, anyway.

        There are rare exceptions to this rule: certain test code and top-level code where you want to catch all kinds of errors (to prevent them from showing up in a UI, or to keep a batch job running). In that case you may catch generic Exception (or Throwable) and handle the error appropriately. You should think very carefully before doing this, though, and put in comments explaining why it is safe in this place.

        @@ -176,17 +174,17 @@ Wildcards in imports

        Every file should have a copyright statement at the top. Then a package statement and import statements should follow, each block separated by a blank line. And then there is the class or interface declaration. In the Javadoc comments, describe what the class or interface does.

        -
        /*
        * Copyright (C) 2007 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.
        */

        package com.android.internal.foo;

        import android.os.Blah;
        import android.view.Yada;

        import java.sql.ResultSet;
        import java.sql.SQLException;

        /**
        * Does X and Y and provides an abstraction for Z.
        */
        public class Foo {
        ...
        }
        -

        Every class and nontrivial public method you writemust +

        /*
        * Copyright (C) 2007 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.
        */

        package com.android.internal.foo;

        import android.os.Blah;
        import android.view.Yada;

        import java.sql.ResultSet;
        import java.sql.SQLException;

        /**
        * Does X and Y and provides an abstraction for Z.
        */
        public class Foo {
        ...
        }
        +

        Every class and nontrivial public method you write must contain a Javadoc comment with at least one sentence describing what the class or method does. This sentence should start with a 3rd person descriptive verb. Examples:

        -
        /** Returns the correctly rounded positive square root of a double value. */
        static double sqrt(double a) {
        }

        /**
        * Constructs a new String by converting the specified array of
        * bytes using the platform's default character encoding.
        */
        public String(byte[] bytes) {
        }
        +
        /** Returns the correctly rounded positive square root of a double value. */
        static double sqrt(double a) {
        }

        /**
        * Constructs a new String by converting the specified array of 
        * bytes using the platform's default character encoding.
        */
        public String(byte[] bytes) {
        }

        You do not need to write Javadoc for trivial get and set methods such as setFoo() if all your Javadoc would say is "sets Foo". If the method does something more complex (such as enforcing a constraint or having an important side effect), then you must document it. And if it's not obvious what the property "Foo" means, you should document it.

        Every method you write, whether public or otherwise, would benefit from Javadoc. Public methods are part of an API and therefore require Javadoc.

        -Android does not currently enforce a specific style for writing Javadoc comments, but youshould -follow theSun Javadoc conventions +Android does not currently enforce a specific style for writing Javadoc comments, but you should +follow the Sun Javadoc conventions .

        Short methods

        @@ -199,10 +197,10 @@ Item 29). By doing so, you increase the readability and maintainability of your

        One exception to this rule concerns try-catch statements. If a variable is initialized with the return value of a method that throws a checked exception, it must be initialized inside a try block. If the value must be used outside of the try block, then it must be declared before the try block, where it cannot yet be sensibly initialized:

        -
        // Instantiate class cl, which represents some sort of Set
        Set s = null;
        try {
        s = (Set) cl.newInstance();
        } catch(IllegalAccessException e) {
        throw new IllegalArgumentException(cl + " not accessible");
        } catch(InstantiationException e) {
        throw new IllegalArgumentException(cl + " not instantiable");
        }

        // Exercise the set
        s.addAll(Arrays.asList(args));
        +
        // Instantiate class cl, which represents some sort of Set 
        Set s = null;
        try {
        s = (Set) cl.newInstance();
        } catch(IllegalAccessException e) {
        throw new IllegalArgumentException(cl + " not accessible");
        } catch(InstantiationException e) {
        throw new IllegalArgumentException(cl + " not instantiable");
        }

        // Exercise the set 
        s.addAll(Arrays.asList(args));

        But even this case can be avoided by encapsulating the try-catch block in a method:

        -
        Set createSet(Class cl) {
        // Instantiate class cl, which represents some sort of Set
        try {
        return (Set) cl.newInstance();
        } catch(IllegalAccessException e) {
        throw new IllegalArgumentException(cl + " not accessible");
        } catch(InstantiationException e) {
        throw new IllegalArgumentException(cl + " not instantiable");
        }
        }
        ...
        // Exercise the set
        Set s = createSet(cl);
        s.addAll(Arrays.asList(args));
        +
        Set createSet(Class cl) {
        // Instantiate class cl, which represents some sort of Set 
        try {
        return (Set) cl.newInstance();
        } catch(IllegalAccessException e) {
        throw new IllegalArgumentException(cl + " not accessible");
        } catch(InstantiationException e) {
        throw new IllegalArgumentException(cl + " not instantiable");
        }
        }
        ...
        // Exercise the set 
        Set s = createSet(cl);
        s.addAll(Arrays.asList(args));
        Loop variables should be declared in the for statement itself unless there is a compelling reason to do otherwise: 
        for (int i = 0; i n; i++) {
        doSomething(i);
        }

        for (Iterator i = c.iterator(); i.hasNext(); ) {
        doSomethingElse(i.next());
        }


        Imports @@ -232,9 +230,9 @@ The use and location of static imports have been mildly controversial issues. So

        We use 8 space indents for line wraps, including function calls and assignments. For example, this is correct:

        -
        Instrument i
        = someLongExpression(that, wouldNotFit, on, one, line);
        +
        Instrument i 
        = someLongExpression(that, wouldNotFit, on, one, line);
        and this is not correct: -
        Instrument i
        = someLongExpression(that, wouldNotFit, on, one, line);
        +
        Instrument i 
        = someLongExpression(that, wouldNotFit, on, one, line);

        Field Names

        • Non-public, non-static field names start with m. @@ -256,10 +254,10 @@ and this is not correct: 
          class MyClass {
          int func() {
          if (something) {
          // ...
          } else if (somethingElse) {
          // ...
          } else {
          // ...
          }
          }
          }

          We require braces around the statements for a conditional. Except, if the entire conditional (the condition and the body) fit on one line, you may (but are not obligated to) put it all on one line. That is, this is legal:

          -
          if (condition) {
          body; // ok
          }
          if (condition) body; // ok
          +
          if (condition) {
          body; // ok 
          }
          if (condition) body; // ok

          but this is still illegal:

          -
          if (condition)
          body; // bad
          +
          if (condition)
          body; // bad

          Line length

          Each line of text in your code should be at most 100 characters long. @@ -277,18 +275,18 @@ Java 1.5 Annotations

          Android -standard practices for the three predefined annotations in Java 1.5's are:

          -@DeprecatedThe @Deprecated annotation must be used whenever the use of the annotated element is discouraged. If you use the @Deprecated annotation, you must also have a @deprecated Javadoc tag and it should name an alternate implementation. In addition, remember that a @Deprecated method isstill +@DeprecatedThe @Deprecated annotation must be used whenever the use of the annotated element is discouraged. If you use the @Deprecated annotation, you must also have a @deprecated Javadoc tag and it should name an alternate implementation. In addition, remember that a @Deprecated method is still supposed to work.

          If you see old code that has a @deprecated Javadoc tag, please add the @Deprecated annotation.

          @OverrideThe @Override annotation must be used whenever a method overrides the declaration or implementation from a super-class.

          For example, if you use the {@inheritdocs} Javadoc tag, and derive from a class (not an interface), you must also annotate that the method @Overrides the parent class's method.

          -@SuppressWarningsThe @SuppressWarnings annotation should only be used under circumstances where it is impossible to eliminate a warning. If a warning passes this "impossible to eliminate" test, the@SuppressWarnings annotationmust +@SuppressWarningsThe @SuppressWarnings annotation should only be used under circumstances where it is impossible to eliminate a warning. If a warning passes this "impossible to eliminate" test, the@SuppressWarnings annotation must be used, so as to ensure that all warnings reflect actual problems in the code.

          When a @SuppressWarnings annotation is necessary, it must be prefixed with a TODO comment that explains the "impossible to eliminate" condition. This will normally identify an offending class that has an awkward interface. For example:

          -
          // TODO: The third-party class com.third.useful.Utility.rotate() needs generics
          @SuppressWarnings({"generic-cast"})
          ListStringblix = Utility.rotate(blax);
          +
          // TODO: The third-party class com.third.useful.Utility.rotate() needs generics 
          @SuppressWarnings({"generic-cast"})
          ListStringblix = Utility.rotate(blax);
          When a @SuppressWarnings annotation is required, the code should be refactored to isolate the software elements where the annotation applies.

          Acronyms in names

          @@ -336,8 +334,8 @@ When a @SuppressWarnings annotation is required, the code should be refactored t

          Both the JDK and the Android code bases are very inconsistent with regards to acronyms, therefore, it is virtually impossible to be consistent with the code around you. Bite the bullet, and treat acronyms as words.

          -

          For further justifications of this style rule, seeEffective Java -Item 38 andJava Puzzlers +

          For further justifications of this style rule, see Effective Java +Item 38 and Java Puzzlers Number 68.

          TODO style diff --git a/pdk/docs/source/documentation.jd b/pdk/docs/source/documentation.jd index 8be570173..4eae07184 100644 --- a/pdk/docs/source/documentation.jd +++ b/pdk/docs/source/documentation.jd @@ -1,14 +1,12 @@ -page.title=Android Compatibility - Compatibility Test Suite +page.title=Documentation Resources doc.type=source @jd:body -

          Documentation -

          -

          +

          As this page grows, it will include resources for wireless operators and handset manufacturers as well as for platform developers.

          -Resources for platform developers +Resources for platform developers

          - + Google I/O videos:
          - + Getting started with the Android source code:
          - + Repo and Git resources:
          - + Documentation on specific tasks:
          diff --git a/pdk/docs/source/download.jd b/pdk/docs/source/download.jd index 9f675121d..065a70897 100644 --- a/pdk/docs/source/download.jd +++ b/pdk/docs/source/download.jd @@ -1,83 +1,16 @@ -page.title=Android Compatibility - Compatibility Test Suite +page.title=Get Android Source Code doc.type=source @jd:body -

          Get source - -

          -
    - eng + eng This is the default flavor. A plain make is the @@ -230,7 +230,7 @@ currently-defined build variants:
    - user + user make user @@ -248,7 +248,7 @@ currently-defined build variants:
    - userdebug + userdebug make userdebug diff --git a/pdk/docs/porting/index.jd b/pdk/docs/porting/index.jd index 9d23fbe4c..76609d222 100644 --- a/pdk/docs/porting/index.jd +++ b/pdk/docs/porting/index.jd @@ -21,7 +21,7 @@ doc.type=porting

    If you are new to Android, start with the platform documentation on the following sites:

    When you are ready to start customizing the platform or porting to your target hardware, start in this guide with the Build System overview.

    diff --git a/pdk/docs/porting/power_management.jd b/pdk/docs/porting/power_management.jd index 542459da8..28f951983 100755 --- a/pdk/docs/porting/power_management.jd +++ b/pdk/docs/porting/power_management.jd @@ -103,7 +103,7 @@ Solid elements represent Android blocks and dashed elements represent partner-sp     		Description
    ACQUIRE_CAUSES_WAKEUP
    		ACQUIRE_CAUSES_WAKEUP
    		Normally wake locks don't actually wake the device, they just cause it to remain on once it's already on. Think of the video player app as the normal behavior. Notifications that pop up and want the device to be on are the exception; use this flag to be like them.
    - - -
    For information about current problems and fixes, see Known issues -.
    -

    This document describes how to set up your local work environment, how to use Repo to get the Android files, and how to build the files on your machine.

    Related reading:
    - -Native libraries
     +Native libraries

    The Android platform makes use of many native libraries, including: