Working with Integrated Libraries in Altium NEXUS

Parent page: More about Components and Libraries

Integrated Libraries reflect Altium NEXUS's Second Generation component management methodology - namely the Integrated Component model. In this model the higher level component is modeled within the schematic symbol in a Schematic library file. Other models are linked from the symbol and component parameters are added to the symbol. All source libraries - symbol and linked models - are defined within an Integrated Library Package project, which is subsequently compiled into a single file; an Integrated Library, or IntLib.

This document takes a look at the various ways in which an integrated library may be created, as well as placement from, and modification to, such a library.

The Benefits of Integrated Libraries

The key benefits of compiling into an integrated library are:

• All component information is available in a single, portable file - since all models are packaged into the integrated library, only one file needs to be available to the project, or moved when the project is relocated. This portability is priceless if you divide your work among different workstations, or want to share your designs with others.
• If a component is placed onto a design schematic from an integrated library, Altium NEXUS is guaranteed to find the right model if it can simply locate the integrated library it came from - no juggling of separated library and model files, where model links can prove very 'brittle', and easily broken by everyday management tasks such as renaming folders on a hard drive.
• From a security perspective, integrated libraries are solid - once they're generated, there's no changing them. In fact, to update an integrated library really means to replace it altogether - you must purposefully pull up the original library package, update the source documents, then recompile.
• These libraries are also checked for integrity when they are compiled. That means they are not only checked for availability, but for correct pin mappings. Even if you want to stay with discrete library files, it is recommended to compile your schematic libraries in an integrated library package, if only to ensure that the source components will map correctly to the target models. Once satisfied, you can ignore the integrated library you've created, and keep placing directly from your schematic libraries.

Creating an IntLib using a Library Package

An Integrated Library Package (*.LibPkg) is a type of Altium NEXUS project which is used to gather together the set of design documents required to produce an integrated library. Schematic symbols are drawn in the Schematic Library Editor, and model references/links defined for each, along with any parametric information. These are stored across one or more schematic library files. Referenced models can include PCB 2D/3D component models, circuit simulation models, and signal integrity models.

The only document that must be added to the integrated library package is the schematic library (or libraries). The files containing PCB 2D/3D component models and simulation models/sub-circuits can be located in any valid search location - within the project, within files in the Installed Libraries list, or down the search path(s) specified for the package.

The library package is then compiled into a single Integrated Library file (*.IntLib).

In summary, there are essentially four steps to creating an integrated library:

1. Create a source library package.
2. Create and add the required source schematic library file(s).
3. Create and add (or point to) the required domain model file(s).
4. Compile the library package to produce the integrated library file.

Creating the Source Library Package

Create a new integrated library package by choosing the File » New » Project command from the main menus. In the New Project dialog that appears, set the Project Type to Integrated Library, specify the name and location for the project, and also its type - Regular, VCS (version controlled), or Managed (as part of an Altium Vault installation) - along with any related options pertinent to that type, as applicable.

After clicking OK, the new, shell library package project will be added to the Projects panel, initially containing no documents.

Creating a new Integrated Library Package (*.LibPkg) through the New Project dialog.

Creating and Adding a Source Schematic Library

Create the source schematic library (*.SchLib) containing the components required. For each component, add the required model links and parametric information. There are two ways to create a source schematic library:

• From scratch, using the File » New » Library » Schematic Library command. Create new components using the Schematic Library Editor, or copy components across from other open schematic libraries.
• From the components that have been already placed on schematic documents in a project, using the Design » Make Schematic Library command.

With the source schematic library (or libraries) prepared, simply add to the library package, using one of the following methods:

• Using the Project » Add Existing to Project command.
• Right-clicking on the entry for the library package in the Projects panel, and choosing the Add Existing to Project command from the context menu.

Source SchLib added to the library package.

Creating and Adding Domain Model Files

Create the models - referenced by the schematic components - in their corresponding files. So PCB 2D/3D component models in a PCB Library (*.PcbLib), and simulation models and sub-circuits in Model (*.Mdl) and Subcircuit (*.Ckt) files respectively. The most important model will of course be the PCB 2D/3D component model which, like its schematic library counterpart, can be created in two ways:

• From scratch, using the File » New » Library » PCB Library command. Create new 2D footprints (and add any 3D body information) using the PCB Library Editor, or copy components across from other open PCB libraries.
• From the PCB 2D/3D component models that have been already placed on the PCB document, using the Design » Make PCB Library command.

Specifying Where to Find the Models

With the model files defined, they now need to be made available to the library package, so that they can easily be located when required - remember, the models are referenced by (or linked to) the schematic components. Altium NEXUS has a standard system for making models available, regardless of whether you are building an integrated library package, or working on a schematic design. There are three ways of making models available:

• Adding the library/model to the project.
• Installing the library/model in the Installed Library list. Here, it will be available to all design projects.
• Defining a search path to the library/model.

There are advantages to each, so choose the method that best suits your work practices. Different models work better with different approaches too, for example you may not want to see a large number of simulation models listed in the Projects panel when the library package is opened, but may like to see the PCB 2D/3D component model libraries. In this case, define a search path to the folder where the simulation models are stored, and add the PCB library to the library package.

Collectively, these three methods of model availability form the Available Libraries (available to a project), and can all be defined from within the Available Libraries dialog - accessed by clicking the Libraries button at the top-left of the Libraries panel.

Define model availability through the Available Libraries dialog.

The PCB library (and other model files if required) can also be added to the library package directly, using the Add Existing to Project command – available from the main Project menu, or from the right-click menu associated to the library package's entry in the Projects panel.

Source PcbLib added to the library package.

Defining search paths to model files - from the Search Path tab of the Available Libraries dialog - simply accesses the Search Paths tab of the Options for Integrated Library dialog (Project » Project Options). Simply add one or more paths as required, remembering that models are searched along these paths in order from top to bottom. Click the Refresh List button to verify that the required model files are indeed being found, and adjust a path if necessary.

An example of a defined search path along which to find the required PcbLib model file.

Compiling the Library Package

With the source libraries added to the library package, and any paths to model files defined as required, the package can now be compiled to ultimately generate the integrated library. Like any other project, the compiler for an integrated library package will generate a list of warning and/or error messages - for example, warning of any models that were not found. Additionally, pin mapping errors can be checked, such as mapping instructions to pads 1 and 2 when the actual footprint contains pads A and K!

Prior to running a compilation, it is prudent to browse through and set the error reporting conditions appropriately, on the Error Reporting tab of the Options for Integrated Library dialog.

It is a good idea to set error reporting options and severity levels as required, prior to compiling the library package.

To proceed with compilation, use the Compile Integrated Library command - either from the main Project menu, or from the right-click menu associated to the library package's entry in the Projects panel. The source libraries and model files are compiled into an integrated library, named after the source library package (<LibraryPackageName>.IntLib). The Compiler will check for violations and any errors or warnings found will be listed in the Messages panel. Fix any problems in the source libraries, and then recompile.

An example error flagged by the Compiler upon compilation of the integrated library package. Hover over the image to see the result of a successful compilation, once any
warnings and errors have been resolved.

The integrated library is saved in the output folder nominated on the Options tab of the Options for Integrated Library dialog (by default a sub-folder of the project's location: \Project Outputs for <ProjectName>). It is automatically added to the Installed Libraries list (available to all projects) and consequently appears available from the Libraries panel.

The compiled integrated library is added to the list of Installed libraries and therefore made available through the Libraries panel.

The Libraries panel offers the only direct view into an integrated library file. Purpose built with integrated libraries in mind, this panel allows browsing of an integrated library by either component, footprint, or 3D model - click the  button to the right of the current library field for controls. When browsing by component, the component to model relationships are presented.

Creating an IntLib from Project Documents

An integrated library can also be made directly from constituent project documents (source schematics and PCB document). Simply use the Make Integrated Library command, available from the main Design menu in either Schematic, or PCB Editors.

The process essentially involves:

1. Opening all source schematic documents and making a schematic library.
2. Making a PCB library from the PCB document.
3. Compiling these libraries into an integrated library, named after the project (<ProjectName>.IntLib).

The IntLib is added to the project (under Libraries\Compiled Libraries in the Projects panel), added to the Installed libraries, and made available through the Libraries panel.

Streamlined creation of an integrated library, directly from the schematic and PCB documents in the active design project.

Creating an IntLib from a Database Library

Related page: Working with Database Libraries

Altium NEXUS's Database Libraries are an ideal choice if you want your Altium NEXUS components to be tightly coupled to your company database. If the design needs to leave your company site, or if you prefer to have your designers work from secure integrated libraries, this can be readily achieved. Altium NEXUS provides the facility to compile an integrated library directly from a database library - either a standard database library (DbLib), or a version-controlled SVN database library (SVNDbLib). In this way, your CAD Librarians can still use database libraries, while your designers use regularly regenerated integrated libraries, working in an 'offline' fashion as it were.

Conversion is performed using the Offline Integrated Library Maker wizard. The process is carried out on a per database table basis, with full control over which tables in the database are considered. A separate integrated library will be generated for each included table.

Convert your database libraries (DbLibs or SVNDbLibs) to 'offline' integrated libraries, using the Offline Integrataed Library Maker wizard.

The process involves the following steps:

1. With the Database Library file (*.DbLib), or SVN Database Library file (*.SVNDbLib) that you want to convert open as the active document, choose the Tools » Offline Integrated Library Maker command from the main menus to access the Offline Integrated Library Maker wizard.
2. Use the Library to Convert page to specify the DbLib, or SVNDbLib to be processed. The active library from which the wizard was accessed will be specified as the library to convert by default. You can freely browse for, and choose, a different database library if required.
3. Use the Options page to specify which of the tables in the linked database are to be included in the conversion. All database tables are included in the conversion by default. To exclude a table, simply ensure that its associated Convert option is disabled. This page of the wizard also enables you to nominate an output directory, in which the generated integrated libraries will be stored. Enter the path to this base directory directly, or click the  icon to the right of the field to access the Browse for Folder dialog, from where you can browse to, and select, the required directory. The generated output (integrated library) for each included database table will be stored in its own sub-folder within the specified output directory, named using the table's name.
4. After choosing the database library and setting the related conversion options as required, click Next to proceed with the conversion. A progress bar will be displayed, along with information on the current database table being converted. Remember that the conversion process is carried out for each database table you have nominated to convert. The following is essentially a breakdown of this process:
   1. An integrated library package (*.LibPkg) is created and opened in the Projects panel. The package is named using the name of the table. For a table named Capacitor - Ceramic for example, this would give Capacitor - Ceramic.LibPkg.
   2. A schematic library document is created and added to the LibPkg. The schematic is again named using the table's name (e.g. Capacitor - Ceramic.SchLib).
   3. Each record in the table is then considered and the appropriate Altium NEXUS component built. To do this, the referenced schematic symbol is retrieved from the appropriate source library and added as a component to the new schematic library document. Parameter and model link information defined in the record is then added to that component.
   4. The referenced footprint model(s) for the record are retrieved and added to a PCB library document. This document is again named after the table (e.g. Capacitor - Ceramic.PcbLib). The PCB library document is then added to the LibPkg.
   5. If the source library is a DbLib, and PCB3D and/or Simulation model links have been defined in the database record, the referenced PCB3D library and Simulation model files are also added to the LibPkg. The location of such models remains unchanged. The full path to a model is specified as part of its corresponding model link.
   6. The LibPkg is then compiled to give the integrated library (e.g. Capacitor - Ceramic.IntLib), which is subsequently added to Altium NEXUS's Installed Libraries.

Results of the conversion process - library package projects with constituent symbol and footprint model documents, and the compiled IntLibs, which are also added as installed
libraries, and therefore made available to all PCB design projects in Altium NEXUS.

Creating an IntLib through Vault Component Acquisition

Related page: Working with the Content Cart

You also have the ability to acquire components from your local Altium Vault, into an Integrated Library. And when placing components from such an Integrated Library, the actual links are back to the Component Items in the vault. This gives you the ability to effectively use your company's Vault components in an offline fashion, while ensuring the design still maintains a true connection to those components in the source vault. It also ensures that the supply chain information defined for those components - through the use of Part Choice Lists - continues to be used.

From the Content Cart dialog, the process to acquire into an IntLib is as follows:

1. Click on the Select target Vault link and choose IntLib file from the menu.

Set the target of the Content Cart to be an IntLib file.

2. Specify the name, and location, for the generated IntLib file. By default, the file will be named in the format Integrated_Library - <Date> - <Time>.IntLib, and generated in the location \Users\Public\Documents\Altium\AD<Version>\Library\ExportCmpLib. Modify this as required through the Save As dialog - accessed by clicking the Change link.

Accept the default target folder, or change as required.

3. If you need to acquire additional components into the same IntLib, click the Add More Items link, then use the subsequent Choose Item dialog to choose those components.
4. Once ready, click the Deliver Cart button to proceed with generation of the IntLib. A temporary Integrated Library Package (*.LibPkg) will be created, with source SchLib (with symbols, parameters and model links) and PcbLib (with footprint models) files generated and added. This is then compiled to produce the IntLib file, which is generated in the specified folder. An information dialog will confirm successful generation of the file.

Deliver the cart to the target folder, which will contain the required Integrated Library file.

After generation, the IntLib is added to the Installed Libraries list - part of the Available Libraries for the software, and will be available for use from the Libraries panel.

The generated IntLib, offering components acquired from your company vault.

Placing Components from an Integrated Library

Placement of components from an integrated library is performed from the Libraries panel. Placement can be made on the active schematic sheet (when browsing the integrated library in Components view) or the active PCB document (when browsing in Components or Footprints views). Placement can be performed in the following ways:

• Select the component entry, click the Place button, then position and click to effect placement in the workspace.
• Click on, and drag the required component, into the workspace.

Use the Libraries panel to place components from an integrated library. While drag and drop is immediate, it will only place a single component instance. Use the Place button to
remain in placement mode.

Modifying an Integrated Library

Integrated libraries are used to place components and cannot be edited directly. To make changes to an integrated library, make modifications in the source libraries first and then recompile the library package to generate a fresh integrated library that includes those changes.

To modify an integrated library:

1. Open the required integrated library's source library package project.
2. Open the source schematic or model libraries to be modified.
3. Make changes as required, save the modified libraries and close them.
4. Recompile the library package. The freshly-generated integrated library will replace the older, existing version.

Decompiling an Integrated Library

There may be occasion where the source libraries in an integrated library need to be accessed for modification, but for whatever reason, there is no access to the original source library package project by which to do so. This is where another aspect of a single, portable integrated library file, comes into play. Although integrated libraries cannot be edited directly, they can be decompiled back into their constituent source symbol and model libraries.

To do this:

1. Open the integrated library that contains the source libraries that need to be modified. Either:
   1. Choose the File » Open command, browse to the integrated library in the Choose Document to Open dialog, and click Open.
   2. Drag and drop the IntLib file from Windows File Explorer onto the Altium NEXUS window.
2. In the Extract Sources or Install dialog that appears, click on the Extract Sources button.

The source schematic and model libraries are extracted and saved in a new folder named after the integrated library's filename - in the folder in which the original integrated library resides.
A library package (<IntegratedLibraryFileName>.LibPkg) is then created and the source schematic and PCB libraries are added to the project, presented in the Projects panel. Simulation model and subcircuit files are not automatically added to the project.

Extracting the source libraries from an integrated library - decompiling to produce a library package project.