Tag Archive: “tcl”

Minimal Tcl/Tk Mac Application Packages

Here is one way to create a self-contained double-clickable Tcl/Tk application for Mac OS X.

Code

Save this text as hello.tcl:

package require Tk
pack [label .l -text "Hello, World!" -padx 30 -pady 30]

For clarity, save this and other example files to the Desktop.

Tclkit

Download and unzip 8.4.16/tclkit-darwin-univ-aqua from the Tclkit download matrix. This is a universal binary version of the latest stable release of Tcl/Tk with native Mac OS X interface elements.

Update: On Mac OS X 10.5 (“Leopard”), at least with current X11 patches, you can use non-Aqua Tclkits as the basis for Mac application packages. X11 will open automatically. Since Tk Aqua doesn’t play well with Leopard, this may prove to be a useful (if ugly) interim solution.

Updatier: The Leopard compatibility problems alluded to above appear to be resolved in Tcl/Tk 8.4.17. Tclkits of 8.4.17 and the official 8.5.0 release are now available.

Updatiest: You can now build your own tclkits with ease using the Kitgen Build System.

SDX

Download sdx.kit from the SDX web page. SDX is a utility that can, among other things, create executable Starpacks by joining Tclkit interpreters with your Tcl code. (Safari may warn that the file is executable and append .sh to its name; just remove the .sh after downloading.)

Files

Open Terminal and change to the directory containing these files:

cd ~/Desktop

Make an executable copy of the Tclkit.

cp tclkit-darwin-univ-aqua tclkit
chmod +x tclkit

The duplicate is needed because Tclkit is used both to execute SDX and as input to SDX. It cannot otherwise operate on itself.

Starpack

Create the Starpack by “quick wrapping” the sample code:

./tclkit sdx.kit qwrap hello.tcl -runtime tclkit-darwin-univ-aqua

This yields the executable file hello, which you can run from the command line:

./hello

Different Tclkits can be used to create executables for different platforms. Omitting the -runtime argument creates a platform-independent Starkit which can be executed by an external Tclkit. Instead of qwrap, more complex projects can use the wrap command to package their entire directory structure as a virtual filesystem.

Icon

Every application needs a good icon. This is not a good icon, but it will suffice as an example:

icon hello.icns

Img2icns is a handy utility for converting images to icns files.

Package

Create a folder called Hello World.app. Because the app extension designates an application, the Finder will treat the folder as an application package. Control-click the embryonic application and select “Show Package Contents”:

Show Package Contents contextual menu

Create a folder called Contents inside the package, and two folders titled MacOS and Resources within Contents. Drag hello.icns into Resources and the hello executable into MacOS.

Info

Every application contains a file that lists certain application properties. Because some properties identify the very components that comprise the application, the application won’t work without this vital file.

Here is an example Info.plist. Place this file in the package’s Contents folder.

Info.plist in Property List Editor

Note that the CFBundleExecutable property identifies the executable (found in MacOS) and that CFBundleIconFile identifies the application icon (found in Resources). The CFBundleIdentifier and CFBundleSignature properties should be unique to your application. The CFBundleGetInfoString, CFBundleShortVersionString, and CFBundleVersion properties specify your application’s version.

Consult Apple’s Property List Key Reference for more details about these and other possible application properties. As XML files, property lists can be edited with text editors or Apple’s dedicated Property List Editor (included with the developer tools).

Showtime

The application package should now be organized like this:

Hello World.app
 /Contents
    Info.plist
   /MacOS
      hello
   /Resources
      hello.icns

It may be necessary to temporarily rename the application in order for the Finder to recognize the new package information. Hello World.app will adopt the hello.icns icon. Give it a double-click:

final application screenshot

The default menu bar items and window title are provided by Tk. The internal main.tcl filename is introduced by qwrap.

So, that’s a tidy way to package a Tcl/Tk program for Mac OS X deployment. The application package is really just a few folders, an icon, and a property list wrapped around a Starpack. If you’re already using Starkits, you’re only a few steps away from delivering a relatively well-integrated Macintosh version of your application.


Credit

The technique described here is largely inspired by Kevin Walzer’s How to Build Tcl/Tk Application Bundles the Mac Way tutorial. The companion article on Tk Aquafication offers more guidance on integration with Macintosh interface conventions.

The example Info.plist is based on the property list included in the Tcl/Tk Aqua 8.4.16 standalone Wish Shell, which I cannot find listed on any relevant web sites. As with other recent releases, it seems to be available only by direct download from mailing list announcements.

Posted on Saturday, December 8th, 2007.

Pdftk 1.41 for Intel Macs

Pdftk is a useful utility for manipulating PDF files. A Macintosh binary of the current version was not available, except perhaps from Fink or Darwin Ports, so I built it myself. My version is not universal, but it doesn’t require a package manager, either.

Until such time as this binary is available directly from the official pdftk site, you can get it here:

Download pdftk 1.41 for Intel Macs 1MB

Note: the default pdftk Makefile settings result in a binary that still relies on gcj. Until such time as this issue is resolved, the binary probably won’t be much use!


Building pdftk requires gcj, which comes with gcc, but apparently not with Mac OS X. So, I downloaded and built GCC 4.2.2. Why 4.2.2? Because it was the most recent version.

./configure --prefix=/usr/local/gcc/4.2.2 --disable-multilib
make
make install

The --prefix option installs everything out of the way in its own little directory; I wasn’t really interested in upgrading to a new version of gcc just to build pdftk. The --disable-multilib option turns off some crap that caused build errors.

Once that’s done, building pdftk is just a matter of pointing the makefile at the new gcc stuff.

cd pdftk
# In Makefile.MacOSX, define TOOLPATH=/usr/local/gcc/4.2.2/bin/
make -f Makefile.MacOSX
make install

So that’s how you roll your own.

Posted on Monday, November 26th, 2007.

strpdf

strpdf creates single-page PDF files populated with one-line text strings. The page size and string placement are configured with command line options. It is a purposely simple tool.

Download

Installation instructions and other notes are included with the downloads.

Usage

Strings are placed on the page with the -text option. General configuration options must be given before the first -text option. PDF data is printed to stdout, so redirection should be used to capture the result.

Here is a simple example:

strpdf -text 'Hello, world!' center middle > helloworld.pdf

The -text option has three parameters. The first is the string to print. The second and third specify the horizontal and vertical locations of the string on the page, respectively. Valid horizontal positions are left, center, and right. Valid vertical positions are top, middle, and bottom. The left, right, top, and bottom positions must each be followed by an additional parameter which specifies the distance from the indicated edge of the page to the closest side of the string.

Multiple instances of the -text option can be used to place multiple strings on the page:

strpdf -text 'Upper right' right 0.5 top 0.5 -text 'Lower left' left 0.5 bottom 0.5 > corners.pdf

The default page size is 8.5 × 11 inches (letter). The -paper option understands a few other common paper sizes, which can be listed with strpdf paper:

strpdf -paper a4 -text 'A4 FTW' center top 1 > a4.pdf

Alternatively, arbitrary page dimensions can be specified with the -width and -height options:

strpdf -width 5 -height 5 -text 'Square' center middle > square.pdf

By default, page dimensions and string position parameters are interpreted as inches. The -units option allows these values to be given in millimeters or points. The supported -units parameters are mm, pt, and in.

The -orient option provides a landscape mode that swaps the width and height of the page. This can be done manually with the -width and -height options, but the landscape option is convenient for use with preset paper sizes:

strpdf -paper legal -orient landscape -text 'Legal fine print' center bottom 0.5 > landscape.pdf

The default font is 12-point Helvetica. The -size option sets the font size (in points) and the -font option sets the font face. If given before the first -text string, these options set the default font. Given after the parameters of a particular -text option, they modify only that string:

strpdf -font Times-Roman -size 18 -text 'One' left 1 top 1 -text 'Two' center top 1 -size 24 -font Courier -text 'Three' right 1 top 1 > fonts.pdf

Valid font faces can be listed with strpdf font. Valid fonts are not necessarily available on your computer, nor are the fonts on your computer necessarily compatible with strpdf.

There is a -compress option which will compress the PDF data if given the
parameter 1, but in most cases it yields little benefit. For small files such
as the examples on this page, compression may actually result in slightly larger files.

Applications

I use strpdf in conjunction with pdftk to “stamp” otherwise static PDF documents with bits of variable text. Because these are both free command line utilities, the process is easily automated and requires no commercial software. Here a registration string is stamped on each page of a report:

strpdf -text 'Registered to John Doe' center top 0.25 > registration.pdf
pdftk document.pdf stamp registration.pdf output registered-document.pdf

Alternatively, strpdf’s output can be piped directly to pdftk:

strpdf -text 'Registered to John Doe' center top 0.25 | pdftk document.pdf stamp - output registered-document.pdf

Posted on Monday, November 26th, 2007.

Instruction Step Fading with PreL3P

By substituting different colors in different parts of a model, PreL3P can be used to create interesting effects such as the step-by-step highlighting seen here:

how to build a silly little doghouse

This page explains how this image was created. It is intended as a demonstration of what can be done with PreL3P, but other relevant topics are discussed. Windows users may be interested in LPub as a more convenient solution.

Color Preparation

Two sets of color code definitions are needed to achieve this effect. A set of modified colors is used first to give parts from previous steps a faded appearance. Then a set of normal colors is loaded to give new parts their vivid hue.

Here are the normal colors from ldconfig.ldr used to draw the current step and the final image:

0 normal.ldr
0 !COLOUR Green  CODE  2 VALUE #008C14 EDGE 0
0 !COLOUR Red    CODE  4 VALUE #C40026 EDGE 0
0 !COLOUR Yellow CODE 14 VALUE #FFDC00 EDGE 0

I used Hex Color Picker along with the standard HSB saturation slider to choose faded versions of these colors. You can use the color picker from any application to do this.

input the normal hex color reduce saturation to 50% output the desaturated hex color

Of course, this approach is not practical for converting large numbers of colors. You’ll have to devise your own system for selecting and generating suitable substitute colors.

Here are the faded colors used for parts from previous steps:

0 faded.ldr
0 !COLOUR Green  CODE  2 VALUE #598952 EDGE 0
0 !COLOUR Red    CODE  4 VALUE #B26676 EDGE 0
0 !COLOUR Yellow CODE 14 VALUE #FBEC87 EDGE 0

Steps

The STEP meta command marks the end of each instruction step in an LDraw model. For example, here are the first three steps of the doghouse model pictured above:

1 2 0 0 0 1 0 0 0 1 0 0 0 1 41539.dat
0 STEP
1 14 50 -24 30 -1 0 0 0 1 0 0 0 -1 3005.dat
1 14 50 -24 -30 -1 0 0 0 1 0 0 0 -1 3005.dat
1 14 -50 -24 0 0 0 -1 0 1 0 1 0 0 3010.dat
0 STEP
1 14 0 -24 50 1 0 0 0 1 0 0 0 1 3009.dat
1 14 0 -24 -50 1 0 0 0 1 0 0 0 1 3009.dat
0 STEP

Most LDraw editors make it easy to create and organize steps. For instance, steps are always shown as part of the model hierarchy in Bricksmith’s “File Contents” drawer:

Steps in Bricksmith

Once a model is complete, its constituent steps can be exported as a series of individual files that represent the model up to that point. In other words, each exported step model is essentially identical to the original model except that it is truncated after the corresponding step.

Rendering each of these partial models produces an image depicting each step in the instructions.

PreL3P Meta Commands

Before proceeding to render the step models, PreL3P meta commands are inserted at the beginning of the file and at the beginning of the most recent step to invoke the appropriate color substitution schemes. The -ldconfig option is used to load the faded.ldr and normal.ldr files prepared above. (PreL3P supports the notion of “LDraw configuration files”—files containing pertinent meta commands; if present, any visible linetypes are ignored.)

By default, PreL3P does not modify the basic color codes understood by L3P. To accomplish step fading, however, it may be necessary to do so. The +codes option tells PreL3P which color codes should be kept in their original form. The special parameter none causes all codes to be converted.

Here is the third step model with meta commands inserted:

0 !PREL3P +codes none
0 !PREL3P -ldconfig faded.ldr
1 2 0 0 0 1 0 0 0 1 0 0 0 1 41539.dat
0 STEP
1 14 50 -24 30 -1 0 0 0 1 0 0 0 -1 3005.dat
1 14 50 -24 -30 -1 0 0 0 1 0 0 0 -1 3005.dat
1 14 -50 -24 0 0 0 -1 0 1 0 1 0 0 3010.dat
0 STEP
0 !PREL3P -ldconfig normal.ldr
1 14 0 -24 50 1 0 0 0 1 0 0 0 1 3009.dat
1 14 0 -24 -50 1 0 0 0 1 0 0 0 1 3009.dat

For each successive step the -ldconfig normal.ldr line should be inserted later in the file. If your editor includes the STEP lines in exported step models, it is fairly easy to locate the beginning of the last step. The correct location can also be found by comparing each step model file to the previous step’s file; the new step starts where the files differ. This is the method used by Travis Cobbs’ shell script.

The first step is a special case since there are no previous steps that need to be faded. You may be able to render it without modification. For consistency, however, you could load the standard color set at the beginning of the file:

0 !PREL3P +codes none
0 !PREL3P -ldconfig normal.ldr
1 2 0 0 0 1 0 0 0 1 0 0 0 1 41539.dat

Note that the preparations are slightly more complex for MPD files. Another -ldconfig faded.ldr command would be needed at the end of the main model to draw submodels from previous steps in the faded colors. Any submodels included in the current step would need to use normal.ldr again. Submodels referenced by the previous step and the current step present a challenge that is left as an exercise for the reader.

Running PreL3P

Once the meta commands have been inserted, the step models can be processed with PreL3P. This replaces the original color codes with hexadecimal values that represent the exact shades defined in the color configuration files.

prel3p -in doghouse3.ldr -out doghouse3-faded.ldr

Rendering

Finally the faded step models are ready to be rendered. PreL3P’s name is a bit of a misnomer; the output works just as well with LDView (note, however, that these hexadecimal colors do not conform to the LDraw format specification, so don’t expect them to work with all LDraw software).

Currently, it is easiest to render a batch of images from the command line. If you save a bunch of command lines to a file named render, you can run them all with sh render (other automation methods may be forthcoming). Here’s what one command looks like:

ldview doghouse3.ldr -SaveSnapshot=doghouse03.png -AutoCrop=0 -SaveZoomToFit=0 -WindowWidth=1024 -WindowHeight=1024 -SaveActualSize=1 -cg30,45 -ModelCenter=0.0,-50,0.0 -ModelSize=250

With LDView 3.2 on Mac OS X, you might need to expand ldview to /Applications/LDView/LDView.App/Contents/MacOS/LDView. Only the first two arguments need to be changed from step to step; the rest specify the size of the output image and ensure that each image will be rendered at the same scale. I’m not particularly familiar with LDView’s command line syntax, so more succinct options may be possible.

Briefly, the -cg option specifies the “latitude and longitude” of the camera on a globe whose origin is specified in LDraw units by the -ModelCenter option. The -ModelSize option controls the distance from the camera to the center of the model. These options work together to ensure the same perspective is used to depict each step. Otherwise, the different dimensions of the individual steps might result in inconsistent default camera positions.

Posted on Friday, October 19th, 2007.

PreL3P

PreL3P preprocesses LDraw files for color compatibility with L3P, which converts LDraw models to POV-Ray format. The current version of L3P (1.3) only knows about some color codes, but it does support arbitrary colors via an extended color syntax. PreL3P replaces LDraw color codes unrecognized by L3P with hexadecimal “extended color” specifications based on the COLOUR definitions provided by your LDraw configuration file. No special material tags are honored besides ALPHA 128 (regular transparency). Color codes can also be mapped directly to other color codes.

PreL3P is a hack to allow models containing contemporary colors to be rendered with L3P and POV-Ray without touching any POV-Ray code. It is not intended to replace other, more expert, solutions to the color quandary; better results can arguably be had by manually including custom POV-Ray color definitions. Ideally, L3P and other programs like Bricksmith would support ldconfig.ldr themselves.

Usage

prel3p # Default: [-in FILE] # stdin [-out FILE] # stdout [-ldconfig FILE] # LDRAWDIR/ldconfig.ldr [+codes none|l3p|CODE[,...]] # l3p (keep codes known by L3P) [-codes none|l3p|CODE[,...]] # none (preprocess all others) [-map IN:OUT] # no mappings [-flag quiet] # not quiet (report completion) [-flag noglob] # glob expansion supported [FILE[,...]] # none (see Alternate Usage) 

Explicit option values override the defaults.

PreL3P can be used as a filter:

prel3p < input.ldr > output.ldr 

Output is not written until the input has been successfully parsed and processed, so files can be preprocessed in place:

prel3p -in model.ldr -out model.ldr 

The codes options permit custom substitution schemes to be specified. The + and - characters represent color codes which should be preserved and color codes which may be replaced, respectively.

prel3p +codes 0 # replace any code other than 0 (black) prel3p -codes 0,71,72 # replace codes 0, 71, and 72, but no others prel3p +codes l3p -codes 4 # preserve color codes known to L3P, except 4 prel3p +codes none # replace every color code (preserve none) 

Unspecified codes are handled according to the behavior implied by the type of the first codes option. +codes implies that other codes may be replaced; -codes implies that other codes should be preserved. Subsequent options of either type modify the initial set.

Color codes can be renumbered with the -map option. For instance, to replace instances of color code 7 with color 8, specify -map 7:8. Mapping occurs before substitution, so if -codes 8 is also specified and a !COLOUR definition for 8 is found, instances of 7 will ultimately be replaced by the hexadecimal equivalent of 8.

A message reporting how many colors were changed and how many lines contained changes is printed when processing is complete. Mappings and color substitutions both constitute color changes.

Color definitions are normally read from LDRAWDIR/ldconfig.ldr (LDRAWDIR is an environment variable assumed to contain the path to your LDraw directory). Different configuration files may be specified with the -ldconfig option. Multiple -ldconfig options may be given, in which case the last of multiple definitions for the same color code takes precedence.

With the exception of color codes, PreL3P’s output is identical to its input. Whitespace, capitalization, and decimal precision are not modified. Unrecognized lines are preserved, as are unrecognized color codes (those not identified by the ldconfig file).

Alternate Usage

If no -in or -out arguments are specified, PreL3P will interpret unrecognized arguments as paths to files to process.

prel3p model.ldr 

The original model.ldr is copied to model.ldr.bak and the processed version is saved in place as model.ldr.

In this context PreL3P understands glob wildcard characters. For instance, in a directory containing only the files model1.ldr, model2.ldr, and model3.ldr, the following commands are equivalent:

prel3p model*.ldr prel3p model?.ldr prel3p model[1-3].ldr prel3p model{1,2,3}.ldr prel3p model1.ldr model2.ldr model3.ldr 

This feature is intended primarily as a convenience for Windows command prompt users since this functionality is typically provided by the command line shell itself on other platforms (unless the argument is quoted). Wildcard expansion can be disabled with the -flag noglob option.

Meta Commands

In addition to the !COLOUR meta command, PreL3P understands unofficial meta commands which allow certain PreL3P command line options to be imbedded in models and configuration files.

The general form of these meta commands is:

0 !PREL3P OPTION VALUE 

where OPTION is one of -ldconfig, +codes, -codes, or -map and VALUE is formatted as the analogous command line parameter.

Options and !COLOUR definitions are read from the input model header after command line options are parsed. The model header is comprised of all input lines preceding the first instance of any LDraw type 1 through 5 lines. Configuration files specified by -ldconfig options in the model header are appended to the configuration file queue and override the default -ldconfig if no explicit value is given on the command line.

Configuration files are parsed sequentially after reading the model header. The entire configuration file is read; LDraw type 1 through 5 lines are ignored. Additional configuration files specified by -ldconfig meta commands within configuration files are parsed at the point they are encountered.

PreL3P meta commands in the model that are not in the model header are parsed and applied as they are encountered during processing. This allows different color substitution schemes to be used for different parts of the model.

Example

Here is a simple LDraw file, bricks.ldr. It uses color codes 89 (Royal Blue), 92 (Flesh), and 72 (Dark Stone Gray).

1 89 0 0 -20 1 0 0 0 1 0 0 0 1 3005.dat 1 92 0 0 0 1 0 0 0 1 0 0 0 1 3005.dat 1 72 0 0 20 1 0 0 0 1 0 0 0 1 3005.dat 

L3P doesn’t recognize these color codes, so it replaces them with the default color 7 (Gray). As a result, the initial rendering looks like this:

L3P substitutes default gray for unknown colors

So, let’s use PreL3P to make a copy of the model with colors L3P can understand:

prel3p -in bricks.ldr -out prebricks.ldr 

The contents of prebricks.ldr:

1 0x029BB2EF 0 0 -20 1 0 0 0 1 0 0 0 1 3005.dat 1 0x02CC8E68 0 0 0 1 0 0 0 1 0 0 0 1 3005.dat 1 0x02635F61 0 0 20 1 0 0 0 1 0 0 0 1 3005.dat 

L3P converts this version of the model without complaint, and the final rendering looks like this:

Correct colors

Changes

1.1:

1.2:

1.3:

1.3.1:

1.4:

Download

The source code may be extracted from any version with SDX. An example localization file is available here.

Posted on Saturday, October 6th, 2007.

Starkits and Starpacks

Tcl scripts are typically interpreted by the Tcl shell, tclsh.

Starkits are single files that contain a virtual filesystem populated with Tcl scripts and other files. Starkits are interpreted by Tclkits, which are single files containing entire Tcl installations.

A Starpack is a Starkit joined to a Tclkit. It is a single executable file that contains a script and the interpreter needed to run it.

Why

Packaging Tcl/Tk scripts as Starkits is advantageous because it allows the set of files that comprise an application to be distributed and installed as a single file.

Likewise, Tclkits allow the complex set of files that comprise a Tcl/Tk installation to be managed as a single file. This confers advantages to the developer (easily test against different interpreter releases) and to the user (installation is simple—as is uninstallation).

Because they have no prerequisites, Starpacks are ideal for distribution to casual users. Since each Starpack contains a generic Tclkit, expert users may opt to save space by installing a single Tclkit to execute individual application Starkits.

How

Tclkits come in many flavors. You can run a Starkit with a Tclkit of your choice by calling it explicitly:

./tclkit-darwin-univ Starkit.kit

If a Tclkit is installed as tclkit, it is used implicitly when you execute a Starkit directly:

cp tclkit-darwin-univ /usr/local/bin/tclkit
./Starkit.kit

Starpacks are executed directly:

./Starpack

The leading ./ characters imply that the executable is in the current directory.

Starkits and Starpacks can be created and disassembled with SDX, itself a Starkit. You can use SDX to create a Starpack of itself.

Posted on Monday, October 1st, 2007.

LDMerge

LDMerge is a console program for merging and unmerging the contents of multiple LDraw directory structures. Multiple part libraries may be used to manage unofficial parts. Some LDraw-compatible programs support this concept, but others do not. By providing a way to temporarily combine several part libraries, this utility facilitates those tools which recognize only a single LDraw directory — without forcing you to adopt the same convention.

Unlike its predecessor LDLink, LDMerge does not rely on symbolic links.

Overview

LDMerge performs two actions: merge and unmerge.

Both actions are applied to a target library. Merging adds parts to the target libary and unmerging removes those parts from the target library.

A source library provides the parts that are merged. More than one source can be merged into the same target. Parts from all sources or from one particular source can be unmerged.

An index file records the source of each merged part.

LDMerge considers an LDraw part library to be a directory containing the subdirectories parts, parts/s, p, and p/48. Files of any type within these subdirectories are considered parts. Other files and folders in the library but not within those specific subdirectories are ignored.

Usage

LDMerge accepts command line arguments corresponding to each of the key terms introduced above.

ldmerge merge|unmerge
        [-target LDRAWDIR]
        [-source LDRAWDIR|all]
        [-index FILE]
        [-mode copy|move|link]
        [-flag verbose]

The first argument is required and specifies the action: merge or unmerge.

If -target is not specified, the value of the LDRAWDIR environment variable is used.

If -source is not specified, it is assumed to be the target’s Unofficial subdirectory. (LDView can automatically download unofficial parts to this location.) The special all source is meaningful only when unmerging.

If -index is not specified, the file ldmerge.ldr in the target directory is used.

The -mode option allows you to specify how parts are merged. By default, part files are copied from the source to the target. If the move mode is used, the source files themselves are moved to the target directory. They are returned to the source directory when unmerged. The link mode creates symbolic links (on Mac OS X or Linux) or hard links (on Windows NTFS systems) to the source files. Moving or linking can be faster, but copying may present the fewest complications. It is not necessary to specify a -mode when unmerging.

Specify -flag verbose to print a line reporting each merge or unmerge operation.

Examples

To merge unofficial parts downloaded by LDView with the rest of your part library, the following command may be sufficient:

ldmerge merge

That copies each part from LDRAWDIR/Unofficial to the corresponding subdirectories of LDRAWDIR, and records the merges in LDRAWDIR/ldmerge.ldr. The default merge can be reversed with the following command:

ldmerge unmerge

This merge command moves the actual source files to the target library:

ldmerge merge -source /Custom/LDraw -mode move

To restore the main library to its original state by removing all merged files, use this command (merged files will be returned to their original location if they were moved):

ldmerge unmerge -source all

A merge can be made permanent by removing the relevant lines from the merge index.

LDMerge will not replace parts in the target library unless the existing merge index indicates that they came from the current source library. Part conflicts and other recognized exceptions are reported; merging or unmerging proceeds if possible. Errors copying, moving, or linking files cause the program to stop.

Parts are identified by filename. File contents are not examined.

Index Format

The index records are formatted as LDraw meta commands. At present, this choice of format is arbitrary, but it may facilitate interesting possibilities in the future.

0 !LDMERGE /Target/LDraw/parts/part.dat SOURCE /Source/LDraw/parts/part.dat

Each record documents a merged part in the target library. The path to this part is stated after the !LDMERGE token. Subsequent parameters may appear in any order and are interpreted as “PARAMETER value” pairs. Presently only the SOURCE parameter is used; it specifies the part’s original location.

Records without SOURCE parameters are valid. They effectively “reserve” parts. If present, the part cannot be removed; if not present, the part cannot be added.

Index lines that cannot be interpreted as LDMerge records are ignored but retained. They appear before all valid records in the updated index.

Paths may contain whitespace, in which case they appear quoted in curly braces.

Downloads

LDMerge is currently available in three forms:

The source code may be extracted from any version with SDX. LDMerge is localizable; see en_us_example.msg for more details. LDMerge is public domain software.

Changes

1.1:

Posted on Monday, October 1st, 2007.