Difference between revisions of "Document Mozilla External String Guide"

From CDOT Wiki
Jump to: navigation, search
(→‎Add External String capability to analysis Makefile.in)
 
(10 intermediate revisions by the same user not shown)
Line 36: Line 36:
 
== Project Details ==
 
== Project Details ==
  
−
When the various versions of the project are being released they will be released on MDC at [https://developer.mozilla.org/User:EndersTruth/sandbox/En/Mozilla_external_string_guide Sandbox:Mozilla external string guide] and later at [https://developer.mozilla.org/En/Mozilla_external_string_guide Mozilla external string guide]
+
<s>When the various versions of the project are being released they will be released on MDC at [https://developer.mozilla.org/User:EndersTruth/sandbox/En/Mozilla_external_string_guide Sandbox:Mozilla external string guide] and later at [https://developer.mozilla.org/En/Mozilla_external_string_guide Mozilla external string guide]</s>
 +
 
 +
At the moment the project is released in it's final place, though it will still be edited there. It is at [https://developer.mozilla.org/En/Mozilla_external_string_guide https://developer.mozilla.org/En/Mozilla_external_string_guide] and any further changes should be made there.
  
  
 
=== Projected Project Time-line ===
 
=== Projected Project Time-line ===
 +
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
 
! Version !! Details  
 
! Version !! Details  
Line 50: Line 53:
 
|-
 
|-
 
| 0.3 || Complete all generic sections from the wiki page and add other important sections about the code
 
| 0.3 || Complete all generic sections from the wiki page and add other important sections about the code
 +
|}
 +
 +
 +
{| class="wikitable" border="1"
 +
! Version !!  Details
 +
|-
 +
| 0.4 || While conversing with the community about  solutions to the Function Pointer Parameter Bug (Bug: 530175), a majority of missing information in the  documentation will have been added.
 +
 +
|-
 +
 +
| 0.5 || The Function Pointer Parameter Bug corrected  and Static Analysis information refreshed.
 +
 +
|-
 +
 +
| 0.6 || I suspect that one or both of the above  releases will have an overflow which will be brought over to a later  release.
 +
 +
|-
 +
 +
| 0.7 || With the added content the layout will be  modified, tested, and standardized.
 +
 +
|-
 +
 +
| 0.8 || Any additional information which should be  covered in the documentation, but isn’t, will be collected and listed. I  am thinking I might post to a mailing list asking others what should be  added. This release will include a list of the new additions after  being collected, researched, and refined.
 +
 +
|-
 +
 +
| 0.9 || The missing information found in the previous  release will be thoroughly researched and populated. Since the  information from early releases (0.1 – 0.3) has been used to create a  nice layout this information should be entered using that layout and not  require reformatting.
 +
 +
|-
 +
 +
| 1.0 || In preparation for this release the  documentation will be looked over with a fine-toothed comb and polished.  This includes making sure the layout is consistent and clean, making  sure spelling, grammar, and references used internally with Mozilla  (function name, macros, ect.) are correct. Only after these things have  been checked will the technical data be reviewed again. This is because  most of it has been checked once already, there is reason to believe the  information was entered correctly the first time (don’t strike me  down,)  and the process is time consuming.
 +
 
|}
 
|}
  
  
 
=== Project Related Bugs ===
 
=== Project Related Bugs ===
 +
 
{| class="wikitable" border="1"
 
{| class="wikitable" border="1"
 
! Number !! Related Ver. No. !! Title  
 
! Number !! Related Ver. No. !! Title  
 
|-
 
|-
−
| [https://bugzilla.mozilla.org/show_bug.cgi?id=529978 529978] || 0.2 || xpcom analysis Makefile produces error about ".deps"
+
| <s>[https://bugzilla.mozilla.org/show_bug.cgi?id=529978 529978]</s> || 0.2 || xpcom analysis Makefile produces error about ".deps"
 
|-
 
|-
−
| *N/A || 0.2 || xpcom analysis type-printer.js qualified member problem
+
| [https://bugzilla.mozilla.org/show_bug.cgi?id=530166 530166] || 0.2 || xpcom analysis type-printer.js qualified member problem
 
|-
 
|-
 
| *N/A || 0.2 || xpcom analysis Makefile for external linkage
 
| *N/A || 0.2 || xpcom analysis Makefile for external linkage
 +
|-
 +
| [https://bugzilla.mozilla.org/show_bug.cgi?id=530175 530175] || 0.2 || type-printer.js error with function pointer parameter
 
|}
 
|}
 
*N/A means the bug is not submitted at this time.
 
*N/A means the bug is not submitted at this time.
 +
Strikethrough  means the bug has been closed
  
  
Line 74: Line 113:
 
|-
 
|-
 
| October 19th, 2009 || The projects sandbox page is now available: [https://developer.mozilla.org/User:EndersTruth/sandbox/En/Mozilla_external_string_guide Sandbox:Mozilla external string guide]
 
| October 19th, 2009 || The projects sandbox page is now available: [https://developer.mozilla.org/User:EndersTruth/sandbox/En/Mozilla_external_string_guide Sandbox:Mozilla external string guide]
 +
|-
 +
| November 20th, 2009 || A crude example of the static-analysis is posted: [https://developer.mozilla.org/User:EndersTruth/nsAString nsAString (external)] (This will be fixed over time.)
 +
|-
 +
| December 13th, 2009 || 0.3 is released! [https://developer.mozilla.org/En/Mozilla_external_string_guide Mozilla external string guide]
 +
|-
 +
| January 22th, 2010 || 0.4 is out, the first since Winter break [https://developer.mozilla.org/En/Mozilla_external_string_guide Mozilla external string guide] [http://enderstruth.wordpress.com/2010/01/22/release-0-4/ 0.4 release blog post]
 +
|-
 +
| February 5th, 2010 || 0.5 is noted, though some of the work is not on the MDC pending refinements [http://enderstruth.wordpress.com/2010/02/05/0-5-release/ 0.5 release blog post]
 +
|-
 +
| February 6th, 2010 || Bug 529978 is resolved and checked in! (See: [[Document_Mozilla_External_String_Guide#Project_Related_Bugs)]]
 +
|-
 +
| February 19th, 2010 || 0.6 is released! [http://enderstruth.wordpress.com/2010/02/19/0-6-release/ 0.6 Release]
 +
|-
 +
| March 15th, 2010 || 0.7 is released!  [http://enderstruth.wordpress.com/2010/03/15/0-7-release/ 0.7 Release]
 +
|-
 +
| March 26th, 2010 || 0.8 isn't released! But while I published 0.9 I also included [http://enderstruth.wordpress.com/2010/03/29/what-was-supposed-to-be-0-8-release/ What was supposed to be 0.8 Release]
 +
|-
 +
| April 12th, 2010 || 0.9 is released!  [http://enderstruth.wordpress.com/2010/04/12/0-9-release/ 0.9 Release]
 +
|-
 +
| April 23rd, 2010 || 1.0 Release [http://enderstruth.wordpress.com/2010/04/23/release-1-0/ Release 1.0]
 
|}
 
|}
 +
 +
 +
== Unofficial scripts and patches ==
 +
 +
=== Add External String capability to analysis Makefile.in ===
 +
 +
[[File:external_makefile.diff]]
 +
 +
 +
diff -r fe80dd3ebe74 xpcom/analysis/Makefile.in
 +
--- a/xpcom/analysis/Makefile.in        Wed Nov 11 19:11:57 2009 -0600
 +
+++ b/xpcom/analysis/Makefile.in        Wed Nov 18 22:33:53 2009 -0500
 +
@@ -1,35 +1,46 @@
 +
  DEPTH = ../..
 +
  topsrcdir = @top_srcdir@
 +
  srcdir = @srcdir@
 +
  VPATH = @srcdir@
 +
 +
  include $(DEPTH)/config/autoconf.mk
 +
 +
+#This has to be set above rules.mk to work
 +
+#It is okay even while building classapi_external
 +
+#type-printer-external.cpp undefines it
 +
  MOZILLA_INTERNAL_API = 1
 +
 +
-
 +
  include $(topsrcdir)/config/rules.mk
 +
 +
-DUMP_CLASSES = \
 +
-  nsAString_internal \
 +
-  nsACString_internal \
 +
-  $(NULL)
 +
-
 +
  SPACE = $(NULL) $(NULL)
 +
  COMMA = ,
 +
 +
  HGREV = $(shell hg -R $(topsrcdir) id -i)
 +
 +
+classapi_internal: typeprinter = type-printer.cpp
 +
+classapi_internal: DUMP_CLASSES = \
 +
+                    nsAString_internal \
 +
+                    nsACString_internal \
 +
+                    $(NULL)
 +
+classapi_internal: classapi
 +
+
 +
+classapi_external: typeprinter = type-printer-external.cpp
 +
+classapi_external: DUMP_CLASSES = \
 +
+                    nsAString \
 +
+                    nsACString \
 +
+                    $(NULL)
 +
+classapi_external: classapi
 +
+
 +
  classapi: DEHYDRA_MODULES = $(srcdir)/type-printer.js
 +
  classapi: TREEHYDRA_MODULES =
 +
  classapi: DEHYDRA_ARGS += --dump-types=$(subst $(SPACE),$(COMMA),$(strip $(DUMP_CLASSES))) --rev=$(HGREV)
 +
  classapi: $(MDDEPDIR)
 +
-      $(CCC) $(OUTOPTION)/dev/null -c $(COMPILE_CXXFLAGS) $(srcdir)/type-printer.cpp >classapi.out 2>&1
 +
+      $(CCC) $(OUTOPTION)/dev/null -c $(COMPILE_CXXFLAGS) $(srcdir)/$(typeprinter) >classapi.out 2>&1
 +
        perl -e 'while (<>) {if (/DUMP-TYPE\((.*)\)/) {print "$$1 ";}}' <classapi.out >dumptypes.list
 +
        perl -e 'while (<>) {if (/GRAPH-TYPE\((.*)\)/) {print "$$1 ";}}' <classapi.out >graphtypes.list
 +
        $(EXIT_ON_ERROR) \
 +
        for class in `cat graphtypes.list`; do \
 +
          dot -Tpng -o$${class}-graph.png -Tcmapx -o$${class}-graph.map $${class}-graph.gv; \
 +
        done
 +
        $(EXIT_ON_ERROR) \
 +
        for class in `cat dumptypes.list`; do \
 +
 +
[[File:add-type-printer-external.diff]]

Latest revision as of 15:19, 1 June 2010

Project Name

Document Mozilla External String Guide


Project Description

On MDC the Mozilla internal string guide makes reference to a Mozilla external string guide which does not exist at this time.

For any developer looking for information on external strings this is a problem. It is specifically important to those developing Extensions, XULRunner applications, and embedders. At the wiki Mozilla internal string guide the link "here" in the sentence of the first paragraph:

"Extensions, XULRunner applications, and embedders should use the external strings, documented here."

points to nothing.

Mozilla internal string guide on MDC

Bug 494970 - Document Mozilla External String Guide


Project Leader(s)

User:Roger_Dicke


Project Contribution

Here are some ways you can help with my project:

  1. Visit the Mozilla external string guide (Or if that fails to exist or seems alright Sandbox:Mozilla external string guide) and help with formatting, spelling, grammar, and anything else you can fix. (Be sure to refer to the How to help page on MDC.)


Project Contributor(s)

Project Details

When the various versions of the project are being released they will be released on MDC at Sandbox:Mozilla external string guide and later at Mozilla external string guide

At the moment the project is released in it's final place, though it will still be edited there. It is at https://developer.mozilla.org/En/Mozilla_external_string_guide and any further changes should be made there.


Projected Project Time-line

Version Details
0.0 Project Plan (This project page and blog post)
0.1 Document the difference between External and Internal strings, lay out wiki page with basic sections
0.2 Data collected and entered using static analysis tool (related interfaces etc.)
0.3 Complete all generic sections from the wiki page and add other important sections about the code


Version Details
0.4 While conversing with the community about solutions to the Function Pointer Parameter Bug (Bug: 530175), a majority of missing information in the documentation will have been added.
0.5 The Function Pointer Parameter Bug corrected and Static Analysis information refreshed.
0.6 I suspect that one or both of the above releases will have an overflow which will be brought over to a later release.
0.7 With the added content the layout will be modified, tested, and standardized.
0.8 Any additional information which should be covered in the documentation, but isn’t, will be collected and listed. I am thinking I might post to a mailing list asking others what should be added. This release will include a list of the new additions after being collected, researched, and refined.
0.9 The missing information found in the previous release will be thoroughly researched and populated. Since the information from early releases (0.1 – 0.3) has been used to create a nice layout this information should be entered using that layout and not require reformatting.
1.0 In preparation for this release the documentation will be looked over with a fine-toothed comb and polished. This includes making sure the layout is consistent and clean, making sure spelling, grammar, and references used internally with Mozilla (function name, macros, ect.) are correct. Only after these things have been checked will the technical data be reviewed again. This is because most of it has been checked once already, there is reason to believe the information was entered correctly the first time (don’t strike me down,) and the process is time consuming.


Project Related Bugs

Number Related Ver. No. Title
529978 0.2 xpcom analysis Makefile produces error about ".deps"
530166 0.2 xpcom analysis type-printer.js qualified member problem
*N/A 0.2 xpcom analysis Makefile for external linkage
530175 0.2 type-printer.js error with function pointer parameter
  • N/A means the bug is not submitted at this time.

Strikethrough means the bug has been closed


Project News

Date News
September 23rd, 2009 The project has started.
October 19th, 2009 The projects sandbox page is now available: Sandbox:Mozilla external string guide
November 20th, 2009 A crude example of the static-analysis is posted: nsAString (external) (This will be fixed over time.)
December 13th, 2009 0.3 is released! Mozilla external string guide
January 22th, 2010 0.4 is out, the first since Winter break Mozilla external string guide 0.4 release blog post
February 5th, 2010 0.5 is noted, though some of the work is not on the MDC pending refinements 0.5 release blog post
February 6th, 2010 Bug 529978 is resolved and checked in! (See: Document_Mozilla_External_String_Guide#Project_Related_Bugs)
February 19th, 2010 0.6 is released! 0.6 Release
March 15th, 2010 0.7 is released! 0.7 Release
March 26th, 2010 0.8 isn't released! But while I published 0.9 I also included What was supposed to be 0.8 Release
April 12th, 2010 0.9 is released! 0.9 Release
April 23rd, 2010 1.0 Release Release 1.0


Unofficial scripts and patches

Add External String capability to analysis Makefile.in

File:External makefile.diff 


diff -r fe80dd3ebe74 xpcom/analysis/Makefile.in
--- a/xpcom/analysis/Makefile.in        Wed Nov 11 19:11:57 2009 -0600
+++ b/xpcom/analysis/Makefile.in        Wed Nov 18 22:33:53 2009 -0500
@@ -1,35 +1,46 @@
 DEPTH = ../..
 topsrcdir = @top_srcdir@
 srcdir = @srcdir@
 VPATH = @srcdir@

 include $(DEPTH)/config/autoconf.mk

+#This has to be set above rules.mk to work
+#It is okay even while building classapi_external
+#type-printer-external.cpp undefines it
 MOZILLA_INTERNAL_API = 1

-
 include $(topsrcdir)/config/rules.mk

-DUMP_CLASSES = \
-  nsAString_internal \
-  nsACString_internal \
-  $(NULL)
-
 SPACE = $(NULL) $(NULL)
 COMMA = ,

 HGREV = $(shell hg -R $(topsrcdir) id -i)

+classapi_internal: typeprinter = type-printer.cpp
+classapi_internal: DUMP_CLASSES = \
+                     nsAString_internal \
+                     nsACString_internal \
+                     $(NULL)
+classapi_internal: classapi
+
+classapi_external: typeprinter = type-printer-external.cpp
+classapi_external: DUMP_CLASSES = \
+                     nsAString \
+                     nsACString \
+                     $(NULL)
+classapi_external: classapi
+
 classapi: DEHYDRA_MODULES = $(srcdir)/type-printer.js
 classapi: TREEHYDRA_MODULES =
 classapi: DEHYDRA_ARGS += --dump-types=$(subst $(SPACE),$(COMMA),$(strip $(DUMP_CLASSES))) --rev=$(HGREV)
 classapi: $(MDDEPDIR)
-       $(CCC) $(OUTOPTION)/dev/null -c $(COMPILE_CXXFLAGS) $(srcdir)/type-printer.cpp >classapi.out 2>&1
+       $(CCC) $(OUTOPTION)/dev/null -c $(COMPILE_CXXFLAGS) $(srcdir)/$(typeprinter) >classapi.out 2>&1
       perl -e 'while (<>) {if (/DUMP-TYPE\((.*)\)/) {print "$$1 ";}}' <classapi.out >dumptypes.list
       perl -e 'while (<>) {if (/GRAPH-TYPE\((.*)\)/) {print "$$1 ";}}' <classapi.out >graphtypes.list
       $(EXIT_ON_ERROR) \
       for class in `cat graphtypes.list`; do \
         dot -Tpng -o$${class}-graph.png -Tcmapx -o$${class}-graph.map $${class}-graph.gv; \
       done
       $(EXIT_ON_ERROR) \
       for class in `cat dumptypes.list`; do \

File:Add-type-printer-external.diff

Retrieved from "https://wiki.cdot.senecapolytechnic.ca/w/index.php?title=Document_Mozilla_External_String_Guide&oldid=40749"