Library Developer Toolkit Version: 9

User Documentation
of the LP_XMLConverter tool

Index

  1. Abstract
  2. File formats of the tool
    1. Library Part Files
    2. XML Files
  3. Parameters and running
    1. Convert directory trees
    2. Convert files
    3. Fix the hierarchy of a library
    4. Make a full library
  4. Compilation for two platforms
  5. Working modes

Abstract

The LP_XMLCoverter tool compiles XML files to ArchiCAD® Library Parts and vice versa on Windows and Macintosh platforms. Usage of the tool faciliates the creation process of ArchiCAD Libraries by the benefit of a cross-platform text-based format for the time of development.

This documentation applies for Version 1.9.

File formats of the tool

The tool uses and generates XML and library part files. A library part file can be unequivocally transformed to one XML file and vice versa without losing any data (when using a correct codepage for transcoding, special characters may get lost otherwise).

The file names must comply with the codepage set in the Regional Settings of the operating system. For example you won't be able to compile a library with Greek file names on Western Codepage.

Library Part Files

The generated files are ArchiCAD library part files with version 21. Consider the main attributes of this file format:
  • A library part has an identifier which consists of two GUID-s.
    The first one is called Main GUID and it identifies the library part discounting the version/revision. This ID is used when the ArchiCAD tries to find a library part to a placed object in a plan (this means that a newer version of a library part can vivify an object).
    The second GUID is called Revision ID and identifies the revision of the library part. When re-saving a library part in ArchiCAD, Main GUID remains the same and RevID gets a new value.
  • The encoding of the texts is a given locale codepage of the OS. This codepage cannot be queried, ArchiCAD presumes that the codepage of the used library is set in the Regional Settings of the OS. When the compiler tool reads / writes a library part, the source / target codepage can be specified explicitly.

XML Files

The XML files are stored in UTF-8 encoding and the line breaks are UNIX linefeeds. The XML format is defined as DTD and as XML-schema as well.

Parameters and running

The tool has some distinct functionalities. These can be grouped into four types.

Convert directory trees (of XML or library part files)

LP_XMLConverter l2x [-l lang] source dest
Converts all library parts (.gsm files) in the given (source) directory tree to XML files into the given (dest) directory recursively. Other files will be copied as binary files (images, .txt, .gdl etc.). 
LP_XMLConverter x2l [-l lang] [-img folder] source dest
Converts all XML files in the given (source) directory tree to library parts into the given (dest) directory recursively. Other files will be copied as binary files (images, .txt, .gdl etc.).
-l lang
Language identifier for text conversion codepage: INT, CEU, BAL, CYR, GRE, TUR, ISR, ARA, THA, JPN, TAI, CHI, KOR.
-img folder
Location of the image library. The images can be refered in the path attribute of picture type nodes (InfoPict, Picture, GDLPict).
source
Source directory of the conversion, the directory must exist.
dest
Destination directory of the conversion, the parent of the directory must exist.

Convert files (XML or library part files)

LP_XMLConverter libpart2xml [-l lang] source dest
Converts the library part file at the location source to an XML at the location dest. 
LP_XMLConverter xml2libpart [-l lang] [-img folder] source dest
Converts the XML file at the location source to a library part at the location dest. If there was a library part at the location dest, it is deleted first. 
LP_XMLConverter copysections [-l lang] source dest
		[section_name [section_type_id] [sub_ident] ...]
Copies the specified sections from the source library part file to the dest XML file.
-l lang
Language identifier for text conversion codepage: INT, CEU, BAL, CYR, GRE, TUR, ISR, ARA, THA, JPN, TAI, CHI, KOR.
-img folder
Location of the image library. The images can be refered in the path attribute of picture type nodes (InfoPict, Picture, GDLPict).
source
Location of the source file of the conversion. The file must extist.
dest
Location of the destination file of the conversion. The parent directory must exist.
section_name
Name of the section to copy from the library part to the XML file. Possible values: SubKind, Drawing, Script_3D, Script_2D, Script_1D, Script_VL, ParamSection, Picture, Ancestry, CalledMacros, Script_UI, Comment, Script_PR, Binary3D, InfoPict, GDLPict, UnknownSection, UNID. If 'UNID', the unique ID of the libpart is copied.
section_type_id
Valid only if section_name is 'UnknownSection'. Specifies the unsigned long value of the section type.
sub_ident
Can specify the subident value of the section to copy. If missing, the default value is 0.

Fix the hierarchy of a library

LP_XMLConverter fixhierarchy libraryLocation [additionalLib ...]
Repairs the ancestry information, the version, the macro-call section and the parameter section of each library part file in the libraryLocation directory tree. The changed library parts get new rev-ID.
libraryLocation
Location of the lirary to fix.
additionalLib
Location of an additional library.

Make a full library

These commands are intended to serve in a make system, where libraries are developed. All of them check whether an XML file changed since the last compilation. For this, the IDEntryList.dbe file is used. In this file, the tool stores the ID and the MD5 checksum of all the source files. This data is used for each file as follows:

  • if the ID of the file is in the list
    • if the stored and the actual checksums match up,
      the file will be skipped (since it is unchanged)
    • if the stored and the actual checksums differ,
      the file will be compiled and the checksum and the ID will be updated in the list
  • if the ID of the file is NOT in the list
    the file will be compiled and its ID and checksum will be added to the list
LP_XMLConverter convertlibrary [options] source dest
Compiles a directory tree of XML files to a directory tree of library parts. Non-XML files will be copied as binary files (images, .txt, .gdl etc.). 
LP_XMLConverter convchecklibrary [options] source dest
Compiles a directory tree of XML files to a directory tree of library parts and checks the consistency of the whole library (ancestry information and macro-call section). Non-XML files will be copied as binary files (images, .txt, .gdl etc.). 
LP_XMLConverter makelibrary [options] source dest [additionalLib ...]
Compiles a directory tree of XML files to a library with a correct hierarchy. So this variant makes a convertlibrary and a fixhierarchy in succession. Non-XML files will be copied as binary files (images, .txt, .gdl etc.). 
LP_XMLConverter finalizelibrary [options] source dest [additionalLib ...]
Does makelibrary and updates 4 sections of the the XML files. These sections are: UNID, Ancestry, CalledMacros, ParamSection. These sections change by re-saving the file (because of the GUIDs) and fixing the inconsistencies (done by fixhierarchy).

The options are: [-l lang] [-s "suffix"] [-img folder] [-check level] [-verbose n]

-l lang
Language identifier for text conversion codepage: INT, CEU, BAL, CYR, GRE, TUR, ISR, ARA, THA, JPN, TAI, CHI, KOR.
-s "suffix"
Optional suffix for names of all target folder. It can be used to distinguish library versions (e.g. Basic Library 9).
-img folder
Location of the image library. The images can be refered in the path attribute of picture type nodes (InfoPict, Picture, GDLPict).
-check checkingLevel
Level of checking done during the compilation - all tests are additional in the ascendent levels:
0 - No checking
1 - Checking GDL Errors
2 - Checking Pictures
3 - Checking generic GDL warnings
4 - Checking .GDL files
5 - Checking precision warnings
-verbose verbosityLevel
Option for setting the verbosity level of printed messages:
0 - Quiet mode
1 - Print compile information (default)
2 - Print all process information
source
Source directory of the compilation.
dest
Destination directory of the compilation.
additionalLib
Location of an additional library.

Compilation for two platforms

Note, that XML files are cross-platform, GSM files are not. (But ArchiCAD can use GSM files from both platforms)
The tool compiles the XML files to a GSM-library for the platform, on whitch it was started. We want to avoid the variance of revision ID-s of the same library part on Windows and on Mac. Different revision ID-s slow down the usage of cross-platform project files a bit. Follow these steps to generate correct libraries with fitting ID-s on both platforms:
  • compile and finalize the library on a platform (finalizelibrary)
  • copy the - updated - XML files to the other platform
  • compile the library (convertlibrary if no change is made between platforms or finalizelibrary if successive compilation is guaranteed)

Working modes

You find some ways to use the tool for library development in this chapter.

GS Server - Edit XML - with manual merge

Necessary Software WIN

  • GSClient - to access the server
  • Merge tool (f. ex.: Araxis Merge) - to merge the changes to the central source
  • XML editor (f. ex.: MS Visual Stuio .NET, XMLSPY, textpad, etc.) - to edit the XML files. For XML validation you have to use a tool which supports this functionality (like XMLSPY).
  • ArchiCAD - to edit library parts
  • LP_XMLConverter tool

CVS-server - Edit GSM - with manual merge

One Working mode

Necessary Software WIN

  • WinCVS - to access the server
  • Merge tool (f. ex.: Araxis Merge) - to merge the changes to the central source
  • ArchiCAD - to edit library parts
  • LP_XMLConverter tool

Necessary Software MAC

  • MacCVS - to access the server
  • Merge tool (f. ex.: FileMerge, CodeWarrior) - to merge the changes to the central source
  • ArchiCAD - to edit library parts
  • LP_XMLConverter tool

CVS-server - Edit XML - with manual merge

Necessary Software WIN

  • WinCVS - to access the server
  • Merge tool (f. ex.: Araxis Merge) - to merge the changes to the central source
  • XML editor (f. ex.: MS Visual Stuio .NET, XMLSPY, textpad, etc.) - to edit the XML files. For XML validation you have to use a tool which supports this functionality (like XMLSPY).
  • ArchiCAD - to edit library parts
  • LP_XMLConverter tool

Necessary Software MAC

  • MacCVS - to access the server
  • Merge tool (f. ex.: FileMerge, CodeWarrior) - to merge the changes to the central source
  • XML editor (f. ex.: Project Space Builder, etc.) - to edit the XML files. For XML validation you have to use a tool which supports this functionality.
  • ArchiCAD - to edit library parts
  • LP_XMLConverter tool
Copyright © 2004 - Graphisoft R&D Software Development Rt. All rights reserved worldwide.