# HG changeset patch
# User Bob Rosenberg <bob.rosenberg@nokia.com>
# Date 1273762664 -3600
# Node ID eccc98839441f070889c46657b5d9e1df6a38557
# Parent  cf27962d27a8088991b3f2668519601f1fff8cd8
Sysdef tools: additional comments and help.

diff -r cf27962d27a8 -r eccc98839441 sysdeftools/filtering.xsl
--- a/sysdeftools/filtering.xsl	Wed May 12 11:29:16 2010 +0100
+++ b/sysdeftools/filtering.xsl	Thu May 13 15:57:44 2010 +0100
@@ -12,14 +12,25 @@
 	Contributors:
 	Description:
 	Filter a sysdef in the 2.0 or 3.0 syntax
+	The functionality of these filters is not supported outside of this tool. 
+	The filtering concepts here may not be carried forward in future system definition processing tools
 -->
 <xsl:output method="xml" indent="yes"/>
 
 <xsl:param name="filter-type">only</xsl:param> <!-- only, has or with -->
 
-<xsl:param name="filter"/> <!-- comma-separated list -->
+<!--
+"only" = every component/unit can only have zero or more of these specified filters. ie, it can only have filters from this list, no other filters are allowed. This covers the common use case of "I want anything with gt and or techview, but no other filters" that was the first step in all old symbian.com builds. 
+
+"has" =  every component/unit must have all of these filters. ie it can have any other filters, but all specified filters must all be present. This covers the case where filter="test" identifies tests and there is no special filter to identify things that are not tests. So a filter for "!test" will strip out anything with filter="test" (plus any other filters) for a production build, and a filter of "test" will strip out everything that does not have filter="test" (plus any other filters) for a test build. Opposite filters will generate sets that are exactly opposite to each other.
 
-<xsl:param name="addbuild" select="0"/> <!-- add a system build section that accepts everything -->
+"with" =  components/units that have the opposite filter are removed. This covers the old symbian.com case of java, !java and "don't care" components. In other words we have a global feature that every item can be built only when the feature is set, only when the feature is not set, or it does not care and will always be built. So for a !java build only items containing filter="java" are stripped out. For a java build, only items with filter="!java" are stripped out. Anything which does not explicitly mention java are always unaffected. Opposite filters will generate sets which overlap.
+-->
+
+
+<xsl:param name="filter"/> <!-- comma-separated list of filters-->
+
+<xsl:param name="addbuild" select="0"/> <!-- add a system build section that accepts everything. Needed for genxml processing -->
 
 
 <xsl:template match="node()|@*"><xsl:copy-of select="."/></xsl:template>
diff -r cf27962d27a8 -r eccc98839441 sysdeftools/joinandparesysdef.xsl
--- a/sysdeftools/joinandparesysdef.xsl	Wed May 12 11:29:16 2010 +0100
+++ b/sysdeftools/joinandparesysdef.xsl	Thu May 13 15:57:44 2010 +0100
@@ -15,11 +15,11 @@
 -->
  	<xsl:output method="xml" indent="yes"/>
 
-	<!-- comma-separated list of IDs in the literal from as the document they appear in (ie same namespace prefix) -->
+	<!-- pare = comma-separated list of IDs in the literal from as the document they appear in (ie same namespace prefix) -->
 <xsl:param name="pare"/>		
 
 
-	<!-- the rank item to pare down. This will remove any item of that rank EXCEPT those in $pare -->
+	<!-- rank = the rank item to pare down. This will remove any item of that rank EXCEPT those in $pare -->
 <xsl:param name="rank">package</xsl:param>
 
 <xsl:variable name="pare-list" select="concat(',',translate(normalize-space($pare),' ',','),',')"/> <!-- accept spaces in pare. Pad with commas to make computing easier -->
diff -r cf27962d27a8 -r eccc98839441 sysdeftools/readme.txt
--- a/sysdeftools/readme.txt	Wed May 12 11:29:16 2010 +0100
+++ b/sysdeftools/readme.txt	Thu May 13 15:57:44 2010 +0100
@@ -12,10 +12,17 @@
 mergesysdef.xsl - Merge two 3.x syntax stand-alone system definitions
 	mergesysdef-module.xsl - XSLT module for merging only two sysdef files according to the 3.0.0 rules
 
-Other Tools:
+Other tools:
 sysdefdowngrade.xsl - Convert a 3.0.0 sysdef to 2.0.1 sytnax
+rootsysdef.pl - Generate a root system definition from a template root sysdef and a set of wildcard paths to look for pkgdef files
 
 XSLT Processing:
 xalan.jar
 xercesImpl.jar
 xml-apis.jar
+
+Validation tools:
+validate/checklinks.pl - check all referenced files in units exist at the specified locations
+validate/modelcheck.xsl - Validate a sysdef file, reporting any errors in HTML format. Can validate a sysdef in a web browser by using <?xml-stylesheet type="text/xsl" href="modelcheck.xsl"?>
+validate/validate-sysdef.xsl - Validate a sysdef file, reporting any errors as plain text
+	validate/test-model.xsl - common module which actually does the validation
diff -r cf27962d27a8 -r eccc98839441 sysdeftools/rootsysdef.pl
--- a/sysdeftools/rootsysdef.pl	Wed May 12 11:29:16 2010 +0100
+++ b/sysdeftools/rootsysdef.pl	Thu May 13 15:57:44 2010 +0100
@@ -1,3 +1,19 @@
+# Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).
+# All rights reserved.
+# This component and the accompanying materials are made available
+# under the terms of "Eclipse Public License v1.0"
+# which accompanies this distribution, and is available
+# at the URL "http://www.eclipse.org/legal/epl-v10.html".
+#
+# Initial Contributors:
+# Nokia Corporation - initial contribution.
+#
+# Contributors:
+#
+# Description:
+#  This will create a new root system definition file based on the provided template
+#!/usr/bin/perl
+
 use strict;
 
 
@@ -25,7 +41,24 @@
 
 my @tdOrder =("hb","se", "lo","dc", "vc" , "pr", "dm", "de", "mm", "ma" , "ui",  "rt", "to" );
 
-# need to add options for controlling which metas are filtered out and which are included inline
+sub help
+	{
+	my $name= $0; $name=~s,^.*[\\/],,;
+	print STDERR "usage: $name  [options...] template\n\nThis will create a new root system definition file based on the provided template by globbing for pkgdefs in the filesystem. Any found pkgdef files are added to the end of their layer or at the end of their tech domain section, if one is defined",
+	"\nvalid options are:\n",
+		"  -path [dir]\tspecifies the full system-model path to the file which is being processed. By default this is  \"/os/deviceplatformrelease/foundation_system/system_model/system_definition.xml\"\n",
+		"\t\tThis is only needed when creating a stand-alone sysdef as the output",
+
+		"  -output [file]\tspecifies the file to save the output to. If set, all hrefs will set to be relative to this location. If not specified all href will be absolute file URIs and this will write to stdout\n\n",
+
+		"  -w [Note|Warning|Error]\tspecifies prefix text for any notifications. Defautls to Error\n\n",
+		"  -root [dir]\tspecifies the root directory of the filesystem. All globbing will be done relative to this path\n\n",
+
+		"  -glob [wildcard path]\tThe wildcard search to look for pkgdef files. eg  \"\*\*\package_definition.xml\". Can specify any number of these.\n",
+		"  -placeholders [bool]\tif set, all packages not found in the template will be left in as empty placeholders\n";
+	exit(1);
+	}
+
 GetOptions
 	(
 	 'path=s' => \$path,
@@ -47,7 +80,11 @@
 # root = -root g:\sf
 # glob = -glob "\*\*\package_definition.xml"
 
-#rootsysdef.pl -root F:\dev\personal\sftest\sf\mcl  -glob "\*\*\package_definition.xml"  -output ..\..\..\deviceplatformrelease\nokia_system\system_definition.sf.xml  ..\..\..\deviceplatformrelease\foundation_system\system_model\system_definition.xml
+#Example command lines:
+#rootsysdef.pl -root F:\sftest\mcl\sf  -glob "\*\*\package_definition.xml"  -output  F:\sftest\mcl\build\system_definition.sf.xml   F:\sftest\mcl\sf\os\deviceplatformrelease\foundation_system\system_model\system_definition.xml
+#rootsysdef.pl -root F:\sftest\mcl\sf  -glob "\*\*\*\*\package_definition.xml"  -output  F:\sftest\mcl\build\system_definition.mine.xml   F:\sftest\mcl\sf\os\deviceplatformrelease\foundation_system\system_model\system_definition.xml
+if(!scalar $ARGV) {&help()};
+
 
 my %replacefile;
 my $dir;
@@ -67,6 +104,7 @@
 
 my $sysdef = &abspath(shift);	# resolve the location of the root sysdef
 
+
 # rootmap is a mapping from the filesystem to the paths in the doc
 my %rootmap = &rootMap($path,$sysdef);	
 my %nsmap;
@@ -103,8 +141,8 @@
 	}
 
 
-# find all the namespaces used in all trhe fragments and use that 
-# to set the namespaces ni the root element of the created doc
+# find all the namespaces used in all the fragments and use that 
+# to set the namespaces in the root element of the created doc
 #   should be able to optimise by only parsing each doc once and 
 #	maybe skipping the contends of <meta>
 my @nslist = &namespaces($sysdef,$sysdefdoc->getDocumentElement());