Macro Build Utility

File:Macro Build Utility Macro Build Utility
Description
This macro provides a Build Utility to assemble multiple project files into one project file. Author: Piffpoof
Author
Piffpoof
Download
None
Links
Macros recipes How to install macros How to customize toolbars
Macro Version
1.0
Date last modified
None
FreeCAD Version(s)
None
Default shortcut
None
See also
None

Description

This macro is intended for use on large projects, ones involving hundreds of objects. It's use on a small single file project would be pointless and unnecessary. However on a large project with many objects and many files to be merged into the final one, it will save time, avoid the user being involved in repetitive actions, and remove human errors.

Installation

All the code for buildUtility.FCMacro is in one macro. So installation is comprised of copying the code to the appropriate Macro directory and invoking the Build Utility from the Macro menu, the Python console or a toolbar button (the preferred method).

Usage

The Build Utility works on the same principals as the build files that are used to assemble large software system (like FreeCAD). A text editor is used to create a text file which adheres to the formats required by the Build Utility. The Build Utility then simply reads each line of the text file and performs the actions specified by that text file.

The macro asks the user for a "build file". It then parses that build file, there are 3 legal line types:

• lines starting with the comment character "#" which are ignored as being comments or remarks
• lines starting with the subfile character "@" which are ignored
  Note: the "@" character is for future enhancement when sub-build files will be handled
• all other lines which may be a project file or a sub-directory

The file extension for Build Utility file is ".FCBld". This is so file do not get mixed up with other uses and applications.

Any file specified in the build file is assumed to have the extension ".FCStd" If the line starts with a directory then the project file is read from that subfolder. Otherwise it is assumed the line specifies a project file. Directories within directories are supported so nesting of arbitrary depths is possible. The file specification format is the "Unix" style with different levels separated by the forward slash character "/".

A new document is created and each project is "Project Merged" into that new and empty document. The document is not saved at the end, this is left for the user if desired. If the file does not exist then the file name is Printed to the Report view

User Interface

There really isn't a GUI at all for this macro. The macro reads a text file that has been prepared with a text editor and produces a model in an output document. Other than clicking the button on the toolbar to start the process, there is no user interaction.

Example

The diagram below shows a file organisation for a project spanning different organizational groups in a company

The contents of the build file shown below shows the file structure for the project described above.

#this is the build file for the complete assembly
#==============================
@sub-build-files - not presently implemented
# first the top-level file
metal
# now some misc files
./black/black
./blue/blue
# file does not exist
zebra 
# folder does not exist
/bear/bear
# multiple files in one sub-folder
./engineering/green
./engineering/grey
#multiple files in hierarchical folders
./externalModules/white
./externalModules/red/red
#./externalModules/red/stackerAssembly - commented out as not currently loading
./externalModules/red/orange
./externalModules/red/level3/yellow

A summary of the file and how it is processed is:

• the first two lines are treated as comments and everything following the initial character of the hash sign is ignored

#this is the build file for the complete assembly
#==============================

• the third line is also ignored because it's first character is the ampersand character which is reserved for future use where command files can invoke other commend files

@sub-build-files - not presently implemented

• the fifth line is the first file specification, the file is in the same directory as the build file, not in a sub-directory

metal

• the seventh and eighth lines are both file specifications where the file is in a sub-directory, note that the sub-directory is of the form "./black/" where "black" is the directory name, so a file called "sheetFold.FCstd" in the directory "outsourcing" would appear "./outsourcing/sheetFold"

./black/black
./blue/blue

• the nineteenth line shows a file specifications which exists but is not being included in this build operation

#./externalModules/red/stackerAssembly - commented out as not currently loading

• the last two lines show file specifications where the file is in more than one level of sub-directory

./externalModules/red/orange
./externalModules/red/level3/yellow

Options

There is no GUI so there are no options. The only alternatives that exist are by using the 3 types of lines in the text file as described above.

Links

none (so far)

Script

not here yet, coming soon