Graphisoft®

Basic Library Version: 10

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
    5. Handle container files
  4. Usage tips
    1. Compilation for two platforms
    2. Handling built-in images
    3. Working modes

1. Abstract

The LP_XMLCoverter tool compiles XML files of a given format 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.8.

2. 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.

2.1 Library Part Files

The generated files are ArchiCAD library part files with version 21. Consider the main attributes of this file format:

2.2 XML Files

The XML files are stored in UTF-8 encoding and the line breaks are UNIX linefeeds. The XML format is defined as XML Document Type Definition (DTD) and as XML Schema Definition (XSD) as well.

All binary sections of the library part - which are not resolved into XML elements - are saved with Windows byte order.

These properties quarantee the full platform independence of the XML format of library parts.

3. Parameters and running

The tool has some distinct functionalities. These can be grouped into five types as follows.

3.1 Convert directory trees (of XML or library part files)

LP_XMLConverter l2x [-l lang] [-img folder] 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.).

-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 folder to create. The images in each library part will be extracted from the GSM file into subfolders and they will be referred in the path attribute of picture type nodes (InfoPict, Picture, GDLPict) in the created XML files.
source
Source directory of the library parts to convert, the directory must exist.
dest
Destination directory for the converted XML files, the parent of the directory must exist.
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 source folder. The images can be referred in the path attribute of picture type nodes (InfoPict, Picture, GDLPict). The compiled library parts will contain the images in themselves.
source
Source directory of the XML files to convert, the directory must exist.
dest
Destination directory for the converted library part files, the parent of the directory must exist.

3.2 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 referred 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.

3.3 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. Every changed library part gets a new rev-ID.

libraryLocation
Location of the (GSM) library to fix.
additionalLib
Locations of additional binary libraries. These libraries are used in fixing the references between library parts (which is based on library part IDs - see GDL Technical Standards Chapter 2.2 for details)

3.4 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:

Non-XML text files (.gdl and .txt) can be stored in Unicode coding, character coding will be transformed to the givel local codepage. Non-XML binary files will be copied unchanged (images and everything except the XML and the foregoing text files).

LP_XMLConverter convertlibrary [options] source dest
Compiles a directory tree of XML files to a directory tree of library parts.
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).
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.
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 referred 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
-interface fileName
Macro library interface definition XML file. When compiling a library without the interface parameter specified, the tool will report all unused macros in separate warnings. In case of a macro library unused macros are the natural intention of the creator and these warnings would shroud other important problems. Consequently, macro libraries should specify their public interface in an XML file (and pass the file to the tool) to omit unused macro warnings for the published macros. The format of the XML file is specified in the XML Schema for Interface Definition file.
-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
Locations of additional binary libraries. These libraries are used in fixing the references between library parts (which is based on library part IDs - see GDL Technical Standards Chapter 2.2 for details)

3.5 Handle container files

A library package can be stored in a Library Container File (LCF) subserviently. The LP_XMLConverter can create and extract such an LCF with the following commands.

LP_XMLConverter createcontainer containerFile [-l lang] [-compress level] libraryFolder [...]

Creates an LCF on the location containerFile containing the passed libraries.

containerFile
Location of the container file to create.
-l lang
Currently it is ignored.
-compress level
Compression level setting. The level must be in the 0 - 9 range. 0 means no compression, 1 is best speed, 9 is best compression. The default is 0.
libraryFolder
Location of one or more library folders which are to be included in the container file.
LP_XMLConverter extractcontainer containerFile [-l lang] libraryFolder

Extracts the LCF on the location containerFile to the libraryFolder folder.

containerFile
Location of the container file to exract.
-l lang
Currently it is ignored.
libraryFolder
Location of a destination folder to contain the content of the LCF to extract.

4. Usage tips

4.1 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:

4.2 Handling built-in images

Library parts can contain "built-in" images. LP_XMLConverter eases the access of this feature, too.

The steps of usage are the following:

  1. Create a folder for the image files and place images in it. The images can be of any format known by ArchiCAD.
  2. Refer the images from the XML files using the following syntax:
    <GDLPict MIME="image/png"
        path="subfoldername/filename.png"
        SubIdent="3"
        platform="Win"
        SectVersion="19"
        SectionFlags="0">
    </GDLPict>
    The 'path' is relative to the main image folder, which is passed to the converter via the 'img' commandline parameter. 'SubIdent' is the inner identifier of the image. This ID can be used to access the image from the scripts.
  3. Use the image in the scripts of the library part containing it. The actual image can be identified by the SubIdent value, as this example shows:
    UI_INFIELD "parName", xPos, yPos, width, height,
            1, 3, 5, 1,        ! mind the "3"
            56, 50, 40, 40,
            1, "",
            2, "",
            3, "",
            4, "",
            5, ""

4.3 Working modes

This chapter describes some ways to use the tool for library development in a versioning system.

4.3.1 CVS-server - Edit GSM - with manual merge

One Working mode
Necessary Software WIN
Necessary Software MAC

4.3.2 CVS-server - Edit XML - with manual merge

Necessary Software WIN
Necessary Software MAC