Update instructions to reflect that the JavaScript ant 'compile' target is broken...

[platform/upstream/libphonenumber.git] / javascript / README

diff --git a/javascript/README b/javascript/README
index 3513820..6327071 100644 (file)
--- a/javascript/README
+++ b/javascript/README
@@ -6,14 +6,20 @@ international phone numbers.
 
 How to setup:
 =============
-1.  Checkout closure-library next to libphonenumber:
+1.  Checkout closure-library, closure-compiler, closure-linter and python-gflags
+    next to libphonenumber:
 
 e.g.
-svn checkout http://libphonenumber.googlecode.com/svn/trunk/ ~/src/libphonenumber
-svn checkout http://closure-library.googlecode.com/svn/trunk/ ~/src/closure-library
+git clone https://github.com/googlei18n/libphonenumber/
+git clone https://github.com/google/closure-library/
+git clone https://github.com/google/closure-compiler.git
+svn checkout http://closure-linter.googlecode.com/svn/trunk/ ~/src/closure-linter
+svn checkout http://python-gflags.googlecode.com/svn/trunk/ ~/src/python-gflags
 
-(Or change the path of the <script src=""> in the html pages to point to
-wherever base.js is located.)
+(If you don't checkout the dependencies next to libphonenumber:
+a. change the path of the <script src=""> in the html pages to point to wherever
+   base.js is located
+b. update javascript/build.xml with the correct paths)
 
 2.  Run the unit tests to make sure everything is working. Open the following
 pages with your web browser:
@@ -23,9 +29,32 @@ pages with your web browser:
 3.  Run the demo: javascript/i18n/phonenumbers/demo.html
 
 
+How to compile:
+===============
+1.  Build Closure's compiler.jar:
+
+e.g.
+ant -f ~/src/closure-compiler/build.xml
+
+2.  Compile the demo.js and all its dependencies to one file: demo-compiled.js:
+
+ant -f javascript/build.xml compile-demo
+
+3.  Run the compiled demo: javascript/i18n/phonenumbers/demo-compiled.html
+
+
+How to use:
+===========
+To use and compile the library in your own project, use the
+javascript/i18n/phonenumbers/demo.js as an example. You will need to
+goog.exportSymbol all the methods you use in your html so that the compiler
+won't rename them. You can then invoke the compiler similarly to how the
+compile-demo ant target in javascript/build.xml invokes it.
+
+
 How to update:
 ==============
-The JavaScript library is ported from the Java implementation (revision 192).
+The JavaScript library is ported from the Java implementation (revision 536).
 When the Java project gets updated follow these steps to update the JavaScript
 project:
 
@@ -33,26 +62,17 @@ project:
     have changed:
   a.  Manually update the .pb.js files with the changes of the .proto files.
   b.  Manually update the toJsArray() Java methods in
-      java/resources/com/google/i18n/phonenumbers/BuildMetadataJsonFromXml.java
+      tools/java/java-build/src/com/google/i18n/phonenumbers/BuildMetadataJsonFromXml.java
+  c.  Build tools/java/java-build/target/java-build-1.0-SNAPSHOT-jar-with-dependencies.jar
+      by running:
+      mvn -f tools/java/java-build/pom.xml package
 
 2.  If the phone number metadata in the XML format has changed
-    (resources/PhoneNumberMetaData.xml)
+    (resources/PhoneNumberMetadata.xml)
     run the following commands to regenerate metadata.js and
     metadatafortesting.js:
 
-    ant -f java/build.xml
-    java -cp java/build/classes \
-      com.google.i18n.phonenumbers.BuildMetadataJsonFromXml \
-      resources/PhoneNumberMetaData.xml \
-      javascript/i18n/phonenumbers/metadata.js false
-    java -cp java/build/classes \
-      com.google.i18n.phonenumbers.BuildMetadataJsonFromXml \
-      resources/PhoneNumberMetaData.xml \
-      javascript/i18n/phonenumbers/metadatalite.js true
-    java -cp java/build/classes \
-      com.google.i18n.phonenumbers.BuildMetadataJsonFromXml \
-      resources/PhoneNumberMetaDataForTesting.xml \
-      javascript/i18n/phonenumbers/metadatafortesting.js false
+    ant -f java/build.xml build-js-metadata
 
 3.  Manually port any changes of the Java code to the JavaScript code:
       PhoneNumberUtil.java => phonenumberutil.js
@@ -60,7 +80,22 @@ project:
       PhoneNumberUtilTest.java => phonenumberutil_test.js
       AsYouTypeFormatterTest.java => asyoutypeformatter_test.js
 
+4.  Run the Closure Compiler to get your changes syntax and type checked.
+    This will also generate demo-compiled.js used by demo-compiler.html
+    (TODO: Use target "compile" rather than "compile-demo" once
+     visibility issues for getExtractedNationalPrefix_ have been resolved):
+
+    ant -f javascript/build.xml compile-demo
+
+5.  Run the Closure Linter to lint the JavaScript files:
+
+    ant -f javascript/build.xml lint
+
 
 TODO:
 =====
 Port functionality to extract phone-numbers from text (findNumbers).
+Port offline phone number geocoder.
+Enable PhoneNumberUtil to handle all digits, rather than a subset
+(JavaScript has no equivalent to the Java Character.digit).
+Port ShortNumberInfo.