AP0145 Working With Version-Controlled Database Libraries

8/13/2019 AP0145 Working With Version-Controlled Database Libraries

1/16

Working with Version-ControlledDatabase Libraries

Version (v1.2) Apr 21, 2008 1

Altium Designer in no way

prohibits a Designer from

performing Librarian-based

activities. Access

rights/permissions defined for the

source control repository will

ultimately define how far the

Designer can drive the Librarian'car'. For example, the Designer

may be able to checkout, open

and modify a library, but is

prevented from committing the

change to the repository.

The ability to place components directly from a database using a Database Library

(*.DBLib) already offers great flexibility and control. Extending this method of linking to

allow source-controlled libraries housing the schematic symbols and footprint models

lifts library and component management to a higher level still.

The source libraries are created, added-to and maintained, within a Subversion-based

repository. The link to the repository and to the external database is defined within an SVN

Database Library file (*.SVNDBLib), an extension of the Database Library file (*.DBLib)

and often referred to as a Version-Controlled Database Library.

Before proceeding further in this document, you should familiarize yourself with the

fundamentals of the database library feature by reading the Using Components Directly

from Your Company Databaseapplication note. Indeed, many of the areas discussed later

assume prior knowledge gained from reading this document.

Librarian or Designer?

There are essentially two modes in which you can work with a version-controlled database library

as a Librarian, or as a Designer.

The use of these roles will differ from company to company. A larger company may have a

dedicated library center which will, in the role of Librarian, solely be involved with the setup and

maintenance of the symbol and model libraries in the source control repository and the

generation of the SVN Database Library file(s). The SVNDBLib file(s) will then be made available

to the Designer(s) within that company, who will install and use the library files from which to

place the components in their designs.

In a smaller company, both roles may be filled by the same person. Not only will that person

setup and maintain the repository of libraries, but will also use the defined SVNDBLib to carry out

the design.

The following sections consider the role of the Librarian and Designer in greater detail.

Working as a Librarian

As a Librarian, not only will you need to set up and maintain the external source control repository of symbol and model

libraries, but you will also be responsible for setting up the SVN Database Library file. This entails: Connecting to the external component database.

Defining database record to component parameter/model mapping.

Specifying the link to the SVN repository in which the symbol and model libraries are stored.

The following sections discuss the repository, configuration of the SVNDBLib file, and also how changes to symbols and models

in the repository-based libraries are made.

The Source Control Repository

The symbol and model library files need to be added to a Subversion (SVN) repository. Addition of such files and management

of folder structure within the repository is performed using an SVN client, such as TortoiseSVN.

One important thing to note when adding files to the repository, is that each symbol and model must be stored in its own libraryfile. In a regular library which can hold any number of symbols/models changing a single entry would result in all being

SummaryThis application note

provides detailed

information on placing

components from a

database using Altium

Designer's SVN

Database Library

feature.
http://ap0133%20using%20components%20directly%20from%20your%20company%20database.pdf/http://ap0133%20using%20components%20directly%20from%20your%20company%20database.pdf/http://ap0133%20using%20components%20directly%20from%20your%20company%20database.pdf/http://ap0133%20using%20components%20directly%20from%20your%20company%20database.pdf/


2/16

AP0145 Working with Version-Controlled Database Libraries

Version (v1.2) Apr 21, 2008 2

In Altium Designer, ensure that

the Provider, on the Version

Control Generalpage of the

Preferencesdialog, is set to SVN

Subversion. Use the Auto

Detect Subversionbutton to

quickly fill the path fields to the

required SVN executables.

marked by the version control system as having been modified. Having one symbol/model per

library file plays to the nature of version control, while allowing you to keep track of exactly what

has been modified and what has not.

For the purposes of this document, it is assumed that the repository has already been created.

For more information on the use of the particular SVN client you are using, refer to the

relevant documentation associated with that software.

For more information on version control, refer to the Working with a Version Control System

tutorial. When reading this document, remember that for a version-controlled database

library, the source control system used must be Subversion.

Using the Library Splitter Wizard

If the libraries for the symbols and models are being newly created, there is no problem ensuring only one symbol/model per

file. Typically however, the source libraries will already exist. To simplify the job of separating these l ibraries into single-entity

files for addition to the SVN repository, Altium Designer provides a splitting tool the Library Splitter Wizard.

Use the initial page of the Wizard to specify the source schematic, PCB and PCB3D libraries that you want to split (Figure 1).

Use the Addbutton to access the Librariesdialog, then browse to and add a library to the list. The source libraries need not

exist in the same folder.

Figure 1. Selecting the existing source libraries to be split.

The subsequent page of the Wizard allows you to specify the output directories into which the (split) individual symbol/model

libraries will be placed.
http://tu0114%20working%20with%20a%20version%20control%20system.pdf/http://tu0114%20working%20with%20a%20version%20control%20system.pdf/


3/16


Version (v1.2) Apr 21, 2008 3

Care should be taken if the original source librariesare stored in the same source directory folder. If

the output directories are not specified and are left

at their defaults pointing to the same source

directory folder you can end up with a very large

mixture of single symbol and model libraries.

Sifting through these when creating the repository

structure may prove very time consuming.

Figure 2. Setting output directories for the libraries to be split.

By default, the output directory will be set to the same directory in which the source

library is stored. As the split library files will be added to the SVN repository, it can

be a good idea to setup the folder structure that you want in the repository in

terms of the symbol/model files locally on your hard disk.

Once the structure is defined, copy the source libraries to their respective folders

within that structure. You can then just leave the output directory settings for each

source library at their defaults. After the split, the generated single library files will

already be in the correct locations. You can then simply delete the original source

library from each folder and add the folders to the repository, using the SVN client

you have decided to use.

The Wizard provides additional options to control how the source libraries are split. For a schematic component library, two

options are provided that allow you to strip the parameter and/or model information from each constituent component leaving

just the bare symbol.

An option is also provided to deal with the situation where an output directory already has libraries in it. You can set this option

to:

Overwrite Existing Files with this setting, existing libraries will be overwritten by newly split libraries of the same name.

Append Incrementing Number To File Names with this setting, the Wizard will scan through the list of output directories

to build a list of existing files to be protected. Each potential split library with the same name as an existing library will be

appended with the suffix _n(where nis an integer, starting from 1).

Once the source libraries and options

have been specified the Wizard will

perform an analysis, the result of which is

the set of single symbol/model libraries

that will be created, listed for you to

review.

The name of each split library to be

generated is shown, as well as the actual

name of the schematic

component/footprint model/PCB3D model

within that library. The original source

library is also listed. The name used for a

library will be the same as that used for

the constituent component/model.

If any of the following characters have

been used in the component/model name,

they will be replaced by an underscore

when creating the library name:

. Figure 3. Reviewing single libraries to be created.


4/16


Version (v1.2) Apr 21, 2008 4

!

'

[

]

Review the list of libraries to be created and then click Nextto proceed with the splitting process and ultimately obtain thelibraries to be added to the source control repository.

Creating the SVN Database Library

Just as the Database Library file is the backbone of the database library feature, so too is the SVN Database Library file the

backbone of the version-controlled database library feature. This file is created and managed using Altium Designer's

SVNDatabaseLib Editor (Figure 4).

An example SVN Database Library Altium Design Library.SVNDBLib can be found in the

\Examples\Reference Designs\SVN DBLibfolder of the installation.

Figure 4. The SVNDatabaseLib Editor.

The SVNDatabaseLib Editor becomes active when the active document in the main design window is a *.SVNDBLibfile.

Create a new file of this type by using the File New Library SVN Database Librarycommand.

Specifying the Link to the External Database

Connection to the external database is carried out in exactly the same way as for a DBLib file. Use the controls available in theSource of Connectionregion of the Editor's main display window to define this connection accordingly.

You can also use the SVN Database Library Conversion Wizard, to quickly create a SVNDBLib from:

An Integrated Library (*.IntLib)

A Database Library (*.DBLib).

Individual schematic component libraries (*.SchLib) and PCB footprint libraries (*.PcbLib).

For more information, refer to the Database Library Migration Toolsapplication note.

Specifying the Link to the Version Control Repository

With a DBLib, the symbol and model libraries are stored on your hard disk or other local/network medium. Remember that for a

SVNDBLib, these libraries are stored under version control in a Subversion repository. As part of the SVNDBLib file, you must

define the link to this repository.
http://ap0143%20database%20library%20migration%20tools.pdf/http://ap0143%20database%20library%20migration%20tools.pdf/


5/16


6/16


Version (v1.2) Apr 21, 2008 6

When searching for a symbol/model

match, the flattened folder paths in the

base symbol or footprint directory are

sorted and searched alphabetically.

If the Library Splitter Wizardis used,

there will always be a corresponding

library with the name of the actual

symbol/footprint.

Specifying Symbol and Model Library Location

When you place a component from an SVN Database Library its

symbol (specified by the [Library Ref]mapping) and footprint

model (specified by the [Footprint Ref]mapping) are

extracted from symbol and model libraries in the version control

repository.

In order to know where in the repository to look for libraries, the

base directories in which these symbol and models reside must be

specified in the SVNDBLib document. These directory paths are

specified on the SVN Repositorytab of the Database Library

Optionsdialog.

In the example of Figure 6, the location for the schematic symbols

and PCB footprint models have been set to point to the following

sub-folders within the repository structure:

The SYMfolder for symbols

The FTPTfolder for footprints.

It is important to stress that the symbols and footprints must reside

within the base repository directories specified. They can of course

be in sub-folders of those directories and the paths specified for

both symbols and footprints can point to the same directory in the

repository. The following methods can be used to locate the

required symbol and footprint model within these nominated base

directories:

Absolute Path the full path to the location of the library can be entered into the database. (e.g.

http://ares/svn/Altium/SVNTest/SchematicSymbols/Capacitor_NonPolarized.SchLib).

Relative Path a relative path (relative to the root of the repository) to the location of the library can be entered into the

database. The URL for the repository specified on the SVN Repositorytab of the Database Library Optionsdialog will

be prefixed to the path you enter, to give the absolute address. Considering Figure 6 for example, if you specify

/SVNTest/SchematicSymbols/Capacitor_NonPolarized.SchLib, the full path will be

http://ares/svn/Altium/SVNTest/SchematicSymbols/Capacitor_NonPolarized.SchLib.

Filename Only you can simply specify the name of the library in which to find the required symbol or footprint, again within

the database record for the component. The first file found with this name will be used. (e.g.

Capacitor_NonPolarized.SchLib).

No Path Information you can opt not to enter any path information in the database

record for the component. When locating the symbol/footprint, the system will initially look

for the first library named like the symbol or footprint itself. For example, if the logical

symbol name in the database (specified by the [Library Ref]mapping) is DIO-

SCHOTTKY-2S, the system will look for the first file named DIO-SCHOTTKY-2S.SchLib

and look for the symbol within this file. If the symbol/footprint cannot be found in this way,

the system will look for a match in all libraries.

If you have defined fields in your database for symbol and footprint path information, these

fields need to be mapped to the appropriate design parameters [Library Path]and

[Footprint Path]respectively.

Not specifying library path information in the database makes it much more robust. The repository location and/or its internal

folder structure could be changed and the database would not need to be updated.

Figure 6. Specifying base repository directories for symbols andfootprints.


7/16


Version (v1.2) Apr 21, 2008 7

Modifying a Database Table through the SVNDBLib File

The occasion will often arise where a change is required to a component record in the database. An existing component may

need one or more of its fields updated to better reflect its current status. A new component may be available for use and

therefore needs to be added to the relevant database table. A component may have been marked as 'obsolete' and, no longerto be used in designs, is required to be deleted from the database altogether.

The SVNDatabaseLib Editor enables you to perform these actions directly, through its Table Browser, eliminating the need to

open the external database. With the required table selected, commands for manipulating its entries in the database are

available from the right-click menu (Figure 7).

Figure 7. Accessing commands to modify the underlying database table.

Editing an Existing Database Component

To edit an existing component in a database table, select its entry in

the Table Browser, right-click and choose the Edit Component

ComponentNamecommand. A dialog for that component will appear

(Figure 8).All of the fields for the parent database table are listed, along with

their values currently defined for the chosen component. Simply

click on a Field Valueentry to edit it.

In Figure 9, the value for the DatasheetDocumentfield, for

component 10ACD33, has been changed to 13-Jun-2006.

As illustrated this change, once made, can be verified in both the

Table Browser and external database table.

Figure 9. Verifying the edit in both Table Browser (SVNDBLib) and database table (MDB).

Figure 8. Editing the database fields for the selectedcomponent.


8/16


Version (v1.2) Apr 21, 2008 8

The folders checked out will be those

specified in the Models Location

region, on the SVN Repositorytab

of the Database Library Options

dialog.

The folder nominated as the local working

directory should only be used to contain acopy of the version-controlled files. Other

files, such as SVNDBLib, MDB, XLS,

should be located in a different directory,

as these are not under version control.

Adding a New Component to the Database

To add a new component to a database table, right-click anywhere within the Table Browser and choose the Add New

Componentcommand. The New Componentdialog will appear.

All of the fields for the parent database table are listed. Simply enter the information for this new physical component as

required. The new component will be added to the bottom of the table (Figure 10).

Figure 10. Adding and defining a new physical component.

Removing a Component from the Database

To permanently remove an existing component from a database table, select its entry in the Table Browser, right-click and

choose the Delete Component ComponentNamecommand. A confirmation dialog will appear clickYesto proceed with the

removal.

Specifying a Local Workspace

As a Librarian, you will routinely modify the component symbols and models stored in the

SVN repository. To make such modifications, you will need to check the files out from the

repository into a local working directory. Create this working directory and then specify it

as the folder to be used on the Version Control SVN Librariespage of the Preferences

dialog (Figure 11).

Figure 11. Specifying a local workspace.

To quickly check out all symbol and footprint model libraries from the repository into the

nominated local working folder, simply run the Check Out All Working Folderscommand

from the SVNDatabaseLib Editor's main Toolsmenu. Figure 12 illustrates the result of such a

checkout, with all files and folders in the local workspace linked and up-to-date with the

content of the repository.


9/16


Version (v1.2) Apr 21, 2008 9

Figure 12. Checkout of repository folders and files to the Librarian's local workspace.

Editing Symbols and Models

Repository and SVNDBLib file aside, the core workload of the Librarian is to maintain the version-controlled libraries. This

involves making modifications to the schematic symbols and models, checked out to the local working folder, then committing

these changes back to the SVN repository.

The main interface between the folders and files checked out to the local workspace, and the repository itself, is the Storage

Managerpanel.

When the SVNDBLib file is the active document, the Storage Managerpanel will populate with the symbol and model folders

checked out to the local working folder. The exact folders listed will be those specified in the Model Locations region, on the

SVN Repositorytab of the Database Library Optionsdialog (Figure 13).

Figure 13. The Storage Manager panel reflects the Librarian's local working folder.

To open a library file for editing, simply right-click on its entry in the All Filesregion of the panel, and choose Openfrom the

context menu that appears. Make changes as required and save the file as normal using the associated Editor's standard Save

command.

A library can also be opened for editing using one of the following methods:

With the SVNDBLib file active, right-click on a component's record entry, on the Table Browsertab, and choose to open

either the schematic symbol or the footprint model.


10/16


Version (v1.2) Apr 21, 2008 10

With the SVNDBLib added to the Available Libraries, simply browse (using the Librariespanel) to the target component

within the linked database, then right-click on its entry and choose to edit either the schematic symbol or the footprint model.

Use the library Editor's File Opencommand to browse to and open, the required library in the local work space.

Drag-and-drop the library file from Window Explorer directly into Altium Designer.

Committing Changes to the Repository

Although there are different ways to open a library for editing, committal of any changes made from within Altium Designer

can only be carried out through the Storage Managerpanel.

One of the most important things to remember as a Librarian when using the Storage Managerpanel, is to refresh the status of

the link between the local working folders/files (displayed in the panel) and the corresponding folders/files in the source control

repository. This is achieved using the Refresh Statuscommand, available from the right-click menu in the All Filesregion of

the panel (Figure 14).


11/16


Version (v1.2) Apr 21, 2008 11

Within Altium Designer, the

controls for committing to, and

updating from, the repository are

solely available through the

Storage Managerpanel. You canof course commit and update

outside of Altium Designer, using

your SVN Client software.

Figure 14. Refreshing the status of the local working copy of the files.

Refreshing the status of the source libraries becomes even more important in a multi-librarian environment, where several

people may be responsible for maintaining the repository of source symbol and model files.

When the local copy of a library is identical in revision to that of the repository, the status will

display as No modification. You are free to open the file and make modifications.

If the status for a library is Out of date, you will need to get the latest version of the file from

the repository updating your own local working copy before you can modify and commit yourown changes. Use the Updatecommand to do this (available from the same right-click menu for

the region).

When you have made and saved changes to a library, the status will change to Locally

modified by me. To push your local changes into the repository, simply right-click on the file's

entry and choose the Commitcommand from the context menu. Once checked in to the repository, the status will return to No

modification.

For more detailed information on the Storage Managerpanel, press F1when the cursor is over the (focused) panel.

Physical Comparison of Revisions

Physical comparison can be performed between any two revisions of the same symbol or model library. This allows you to

clearly see, in a visual manner, the changes that have been made between consecutive or non-consecutive revisions of the

file.

Comparison can be made on one of two levels:

At the local level comparing two versions of the document stored within the Librarian's local workspace. Typically the

current version is compared with a local backup (stored in a History folder, located in the same directory as the source

library). Simply select the two versions of the library you wish to compare, in the Local History region of the Storage

Manager panel, right-click and choose Compare.

At the repository level comparing two revisions of the document stored within the repository itself. Simply select the two

revisions of the library you wish to compare, in the VCS Revisions region of the Storage Manager panel, right-click and

choose Compare.

Once the Comparecommand is invoked, the two selected document revisions will be opened in the workspace, the graphical

comparison is made, and any differences detected between the two will be listed in the Differencespanel. It is a good idea tohave the two documents open side-by-side in the workspace, to easily peruse the differences.


12/16


Version (v1.2) Apr 21, 2008 12

Browsing Differences

Figure 15 shows an example of differences detected between two revisions of the same library file (a schematic component

library).

Figure 15. Detecting physical differences between document revisions.

Differences are listed in a hierarchical fashion. The top-level entry lists the number of differences detected. For libraries, this is

the number of matching parts that are found to be different between the two revisions. For source libraries associated with anSVNDBLib where there is only one symbol/model per file this entry will always be 1.

The next level down lists the

parts found to be different. The

entry marked by a red cross icon

shows the matching parts that

are different. The sub-level

entries correspond to that part on

each separate document. Again,

with a library associated with an

SVNDBLib, there will only be one

matching component.

The next level down lists theactual graphical differences

between the parts or, put another

way, the objects causing the

differences. Again, an entry with

a red cross reflects the matching

object found to be different. The

sub-level entries correspond to

that object on each separate

document.

Clicking on the top-level entry for

a detected difference denoted

by the red cross icon will

highlight that difference on both

documents simultaneously

(Figure 16). Click on the sub-

entry for an object to highlight it

on its parent document

separately.

Figure 16. Graphical comparison directly in the workspace.


13/16


Version (v1.2) Apr 21, 2008 13

Working as a Designer

As a Designer, you will take the SVNDBLib file generated by the Librarian and make it available in the Librariespanel byadding it to the Available Libraries list (Figure 17).

Figure 17. Making the SVN Database Library available for use.

The Librariespanel becomes a 'browsing window' into the linked external database. Browsing database components andsearching for specific components is performed in the same way as for an installed DBLib. For more information, refer to the

sections Browsing the Database Componentsand Searching for a Component, in the Using Components Directly from Your

Company Databaseapplication note.

Localized Cache

When the SVNDBLib file is added to the Available Libraries list, the symbol and model libraries in the repository are cached in a

temporary folder, local to the Designer's computer. When an action in the software calls for the use of a schematic symbol or

model, that symbol/model is retrieved from the local cache.

Automatic Cache Update

The libraries in the cache will be automatically updated with the latest from the source control repository when performing any ofthe following actions within the software:

Placing a component from an installed SVNDBLib file in the Librariespanel.

Performing a design transfer

(i.e. updating the PCB)

Using the Update From

Librariescommand in the

Schematic Editor.

Using the Update From PCB

Librariescommand in the PCB

Editor.

Although the update is automatic, itcan be controlled by the use of an

option available on the Version Control SVN Librariespage of the Preferencesdialog (Figure 18).

Figure 18. Setting the local cache 'update timer'.
http://ap0133%20using%20components%20directly%20from%20your%20company%20database.pdf/http://ap0133%20using%20components%20directly%20from%20your%20company%20database.pdf/http://ap0133%20using%20components%20directly%20from%20your%20company%20database.pdf/http://ap0133%20using%20components%20directly%20from%20your%20company%20database.pdf/


14/16


15/16


Version (v1.2) Apr 21, 2008 15

To perform a full update, including parameters, model and graphical attributes of schematic symbols, use the Update From

Librariescommand (also available from the Schematic Editor's main Toolsmenu).

For further information on using the various update tools, refer to the Keeping Components Up-To-Dateapplication note.

Dual Synchronization SVNDBLib and DBLink

You may have an existing design project where the majority of the placed parts have been linked to an external database usinga DBLink file. Design changes may result in additional circuitry, the components for which might be placed using the SVN

Database Library (SVNDBLib) feature. The associated SVNDBLib file could, quite conceivably, point to a different external

database.

When using the Update Parameters From Databasecommand, all linked parameters for placed components will be queried

across all linked databases, irrespective of the linking method used and detected differences for those parameters displayed

in the Select Parameter Changesdialog.

If the same database field has been used for matching in both the DBLink and SVNDBLib files, the database linked by the

DBLink file will be searched first for a match, followed by the database linked to by the SVNDBLib file. If the component is

present in both databases, you could quite possibly match and update from the wrong external record.
http://ap0144%20keeping%20components%20up-to-date.pdf/http://ap0144%20keeping%20components%20up-to-date.pdf/


16/16


Version (v1.2) Apr 21, 2008 16

Revision History

Date Version No. Revision

20-Jun-2006 1.0 Initial release

14-Jun-2007 1.1 Updated for Altium Designer 6.8

21-April-2008 1.2 Updated Pagesize to A4.

16-Mar-2011 - Updated template.

Software, hardware, documentation and related materials:

Copyright 2011 Altium Limited.

All rights reserved. You are permitted to print this document provided that (1) the use of such is for personal use only and will not be copied or

posted on any network computer or broadcast in any media, and (2) no modifications of the document is made. Unauthorized duplication, inwhole or part, of this document by any means, mechanical or electronic, including translation into another language, except for brief excerpts in

published reviews, is prohibited without the express written permission of Altium Limited. Unauthorized duplication of this work may also be

prohibited by local statute. Violators may be subject to both criminal and civil penalties, including fines and/or imprisonment.

Altium, Altium Designer, Board Insight, DXP, Innovation Station, LiveDesign, NanoBoard, NanoTalk, OpenBus, P-CAD, SimCode, Situs,

TASKING, and Topological Autorouting and their respective logos are trademarks or registered trademarks of Altium Limited or its subsidiaries.

All other registered or unregistered trademarks referenced herein are the property of their respective owners and no trademark rights to the

same are claimed.

Documents

AP0145 Working With Version-Controlled Database Libraries