Working with Projects in Altium Designer

Parent page: Getting Familiar with the Altium Design Environment

The starting point for every design created in Altium Designer is a project. An Altium Designer project is a set of design documents whose output defines a specific implementation.

In a nutshell, Project Management is focused on securely storing and tracking changes throughout the design process, and ultimately, channeling the resulting design through to the creation of a physical item – such as an assembled PCB to be used in the final product. To meet these needs, Altium Designer provides a range of project management approaches that offer increasing levels of sophistication and capabilities, yet simplify the process from a designer's perspective. These range from local file-based storage and management, to local/remote Version Control System (VCS) storage approaches, and through to its advanced and recommended form where the management of design data is centered on the capabilities of a Workspace.

A connected Workspace and its internal VCS service hosts and manages Altium Designer projects, and also provides simplified VCS operations, inherent design collaboration capabilities, advanced design data sharing, history tracking, Lifecycle management, and much more. Projects that are integrated with a Workspace are accessed directly from Altium Designer, such as from the Projects panel, or from the Workspace itself through its browser-based interface.

Thanks to the intelligence built into the services provided by a Workspace, tasks such as VCS operations are simplified and automated, and additional design collaboration features such as user access control (sharing), commenting and history are available directly from within Altium Designer. The end result is a robust and secure project storage format and location that can become the central point for collaborative project design.

For a Workspace project, the following actions are supported:

• Creating a Project – directly, by making an existing local project available in the Workspace, or by cloning an existing Workspace project.
• Opening a Project – to be able to work on it.
• Viewing Project History – browsing a progressive timeline of major events relating to the project – its creation, commits, releases, clones and MCAD exchanges – with various actions supported where applicable.
• Commenting a Project – placing tagged notes on a document that are stored in the Workspace and available to all users that have access to that project document.
• Sharing a Project – changing the access permissions for a project so that users that need to see and work with it have the ability to do so.
• 'Soft' Deleting a Project – removing an entire project to the Workspace Trash location, which has options to permanently delete the project or restore it to its previous location.

Types of Projects

Altium Designer supports a number of different kinds of projects. Below is a brief description of each.

PCB Project

In a Printed Circuit Board (PCB) project, the electronic circuit is captured as a schematic, which is built up from libraries of component symbols that are placed and wired together.

The design is then transferred to the PCB editor where each component is instantiated as a footprint (pattern) and the circuit wiring becomes point-to-point connection lines. A shape for the final PCB is defined, along with the physical layers the board will include. Design rules specify the layout requirements, such as routing widths and clearance. The components are positioned within the board shape, and the connection lines are then replaced by routing, either manually or automatically.

When the design is complete, standard format output files are generated which can be used to fabricate the blank board, configure an assembly machine, and so on.

Projects that are stored and managed in a Workspace are shown with an indicative icon, such as for a PCB project.

Multi-board Project

In a Multi-board project, the logical design is captured using a schematic document that connects together sub-project modules, which in turn represent existing PCB projects. The Multi-board schematic data is then transferred to a Multi-board assembly document where the physical board assemblies, as defined by the sub-projects, are positioned together and within an added enclosure.

A Multi-board project (*.PrjMbd) effectively defines the electrical and physical connectivity between existing PCB design projects through the application of a logical schematic document (*.MbsDoc) and synchronized assembly document (*.MbaDoc).

► Read more about Multi-board Projects.

Integrated Library

An Integrated Library is created in a library package project (*.LibPkg), where schematic symbols are created in a Schematic Library (*.SchLib), and reference links defined to matching models in other domains. Referenced models can include PCB footprints, circuit simulation models, signal integrity models, and three-dimensional mechanical models.

Files that contain the models (PCBLibs, etc) are added to the Integrated Library Package (*.LibPkg), or search paths are defined to identify their location. The source schematic symbol libraries and required models are then compiled into a single file (*.IntLib), referred to as an Integrated Library.

► Read more about Working with Integrated Libraries.

Script Project

A Script (*.pas) contains a set of instructions (automated commands) that are interpreted when it is executed in Altium Designer. The scripts are written and debugged in the same editor environment.

There are two types of Scripts – script units and script forms. A script Unit can use the X2 Application Programming Interface (API) to modify or manipulate design objects on a design document. A script Form hosts controls as a user interface and harnesses the X2 API to provide script dialogs that act on active design documents.

Script Units, Forms and Data Models are contained in a Script project (*.PrjScr).

► Read more about Automating Design Tasks with Scripting.

Projects Panel

The Projects panel displays all projects that are currently open and their constituent documents and structure.

The Projects panel

The behavior of the Projects panel can be configured using the options on the System – Projects panel page of the Preferences dialog. These options can also be accessed using the  control at the top of the panel.

When connected to a Workspace, the Workspace icon ( / ) is shown next to the uppermost entry of this Workspace. When the local working copy of a project is opened but the Workspace where the project resides is not connected, a grayed-out Workspace icon ( / ) will appear, and the project icon will change (e.g. it appears as  for a PCB project).

A Workspace project can also be shared with you without inviting you to the team of the Workspace where this project resides. A project that has been opened from shared access is indicated by an associated Shared with me label with the icon next to it.

If a project was shared with you so you can only view it, the View Only label will be shown next to the project entry in the panel to indicate this.

An indication of a project shared with you to view only.

Local projects are listed under the entry of the project group ( *.DsnWrk) – either the default one (Project Group 1.DsnWrk), or one you have created or opened.

To access the context menu regarding your currently connected Workspace, right-click on your Workspace name or click the  control at its far right. These commands include:

• Open Project – opens the Open Project dialog.
• Create Project – opens the Create Project dialog.
• Show in Explorer – opens the Explorer panel.
• Show in Web Browser – opens the Projects page of the Workspace's browser interface in your default browser.
• Altium 365 Get Started Guide – opens the Altium 365 Get Started Guide will open in your default browser, where you can view the contents of the guide.
• Sign out – signs you out of the Workspace.
• Sign in – signs you in to the Workspace. This command is available provided that you have at least one Workspace item (e.g., project) opened in the Projects panel and you are currently disconnected from the Workspace where this item resides.

You must be connected to a Workspace to access these commands. When signed out of a Workspace, right-click the Workspace you want to connect to, and click the Sign In command.

Project Documents Tree

When you open an existing project or create a new one, its entry will appear in the Projects panel. Any existing documents that are part of a project (and any new ones that have been added) will appear under sub-folders according to their purpose and/or type. For example, the following common folders and content document types can appear under a project:

• Source Documents – core design documents such as schematics, PCBs, etc.
• Settings – provides various files used within the project, including Output Job Files, Harness Definitions Files, and Annotation Documents, among other pertinent files.
• Libraries – local source library documents. Documents are further subdivided based on library type (e.g., schematic libraries, PCB libraries, etc.).
• Documentation – additional documents that have been added to the project, of a type that is known by Altium Designer (e.g., text, PDF, etc.).
• Other Documents – additional documents that have been added to the project, of a type that is not known by Altium Designer. These can be opened by Altium Designer if the owner application is known by Windows (eg, Word documents, Excel spreadsheets, etc).
• Generated – documents generated as output. Documents are further subdivided based on type (e.g., BOM documents, text documents, etc.). As project output is generated, the corresponding sub-folders in the main tree will be created and become populated.
• Components – this folder lists each component and the number of components in each group. Validate the project if this folder does not appear (Project » Validate). Components are grouped by the first letter in the designator by default - right-click on the entry for a component (or component grouping folder) and choose the Component Grouping command from the context menu to quickly access the Components Grouping controls for the Projects panel and change the style of grouping, or disable grouping, as required.
• Nets – this folder lists each net used in the project. Validate the project if this folder does not appear (Project » Validate).

Documents that are stored in the project folder or a sub-folder of the project folder are associated in the project file using relative referencing. Documents that are stored in a different folder path are associated in the project file using absolute referencing. These documents include a small arrow in the bottom corner to indicate that they are linked to the project, as shown by the file in the image above.

Notes on working in the documents tree:

• Any documents that are independent of a project will appear as Free Documents and will appear under corresponding sub-folders. By right-clicking on a free document and choosing the Add to Project <ActiveProjectName> command from the context menu, you can add a currently open free document to the active project. Alternatively, you can drag and drop it onto the required project name, in the Projects panel.
• Along with allowing multiple documents to be open for editing, the environment also supports multiple projects being open at the same time. These could be related or unrelated projects.
• Documents in the Projects panel are automatically arranged in logical groups or 'folders', such as Source Documents (Schematic, PCB, etc.), Settings documents (Harness, Outjob, etc.,) and, in the case of a hierarchical design, top-level schematic documents. The documents within each folder group are displayed by default in the order they were added but can be dragged and dropped to a new order position within the group.
• In the case of a new hierarchical design, the parent-child relationship between documents will be displayed in the panel. Note that the connectivity relationships cannot be defined by dragging and dropping schematic documents since the inter-sheet connections and design hierarchy are in fact defined by Sheet Symbols and Port definitions.
• To close the currently focused project in the Projects panel, right-click on its entry and choose the Close Project command, from the context menu. The active project can be closed by choosing the Project » Close Project command, from the main menus.
• Right-click a project document sub-folder, whether expanded or closed, to access additional document management commands, such as opening, closing, or saving all documents within the focused project document sub-folder.
• Documents can be transferred between projects in the panel by clicking and dragging. The document does not have to be dragged into the correct sub-folder; it will be placed correctly within the project structure automatically.
• The keyboard shortcuts Up Arrow, Home, End, and Down Arrow can be used to display the previous, first, last, and next entry in the panel, respectively. Use the Right Arrow and Left Arrow keys to expand and collapse a top-level entry or its sub-folder, respectively.
• To cross-probe from the selected component or net entry in the Projects panel, to that entity on the schematic or PCB document of the parent PCB design project, right-click on the entry and choose the Cross Probe to Schematic or Cross Probe to PCB command from the context menu.

Project Options

An existing or newly created Project is associated with a range of Option settings that are specific to that project. These are stored in the project file (*.PrjPcb, for example) and will vary depending on the type of project. Note that Server Parameters are stored with the project in its Altium Workspace.

The option settings are configured in the Project Options dialog, which can be accessed from Project » Project Options on the main menu, or by right-clicking on the project name in the Projects panel and then selecting Project Options from the context menu. For the project focused in the Projects panel, the dialog can be accessed by clicking the  control at the top of the panel.

Other project settings that are defined in other dialogs and then stored in the project file include:

• Schematic annotation settings.
• Output settings such as; reports, print, Gerber, and so on. Note that these are the output settings accessed via the schematic or PCB editor menus, rather than the output settings defined in an OutJob document.

Project Saving

When you perform a change on an open project's structure or options, it becomes modified. A modified project is distinguished by an asterisk next to its entry and the  status icon in the Projects panel. To save the changes of a project document file, right-click the project entry in the Projects panel and select the Save command. For the focused project in the panel, it can be saved by clicking the  control at the top of the panel.

For a Workspace project, the Save command will save the changes locally, i.e. only your local working copy of the project document file will be saved. To make the changes available in the connected Workspace, the projects must be saved to this Workspace. Save the selected files by right-clicking on a project and selecting Save to Server or by selecting the Save to Server link next to the project file.

Clicking the link and selecting the command saves any source design documents that have been modified but not yet saved locally and opens the Save to Server dialog in which you can select the documents to be saved to the Workspace. After clicking OK, the documents are saved to the Workspace and the Save to Server link disappears from the Projects panel.

Saving when Closing a Project

If you close a project and that project has two or more modified documents that have not yet been saved, the Confirm Save for Modified Documents dialog will open. Use this dialog to decide what to do with those documents.

Use the Confirm Save for Modified Documents dialog to decide how to handle unsaved documents when closing one or more projects or Altium Designer itself.

The main area of the dialog lists all open and modified documents (by name and path to the local copy) for which you need to make a decision about whether or not to save. Documents are grouped by type (e.g., PCB Documents, PCB Projects, Schematic Documents, BOM Documents and so on).

The possible decisions are listed below. Which decisions are actually presented for a document will depend on whether that document is local or Workspace-based and, if the latter, whether or not that document has also been saved locally already.

 - this decision is available for a local document or for a Workspace document that has not already been saved locally. In the case of the latter, it allows you to save the document locally without committing changes to the connected Workspace.

 - this decision is available for a local document or for a Workspace document that has not already been saved locally. Any changes to the document will be discarded.

 - this decision is available for a Workspace document, irrespective of whether it has already been saved locally or not. Changes to the document will be saved locally (where applicable) and to the connected Workspace.

 - this decision is available for a Workspace document when it has already been saved locally. Since there is nothing to save locally, nothing will be done with this document.

The following buttons are available at the bottom of the dialog to quickly make decisions en-masse:

 - use this button to quickly set decisions for each document in a 'save locally' way. For a local document or Workspace document that has not already been save locally, its decision will be set to Save. For a Workspace document that has already been save locally, its decision will be set to Do nothing.

 - use this button to quickly set decisions for each document in a 'save none' way. For a local document or Workspace document that has not already been save locally, its decision will be set to Don't Save. For a Workspace document that has already been save locally, its decision will be set to Do nothing.

 - use this button to quickly set decisions for each document in a 'save fully' way. For a local document its decision will be set to Save. For a Workspace document its decision will be set to Save to Server.

Project Groups

In Altium Designer, you can open and edit multiple projects, and if desired, save the collective set of projects as a Project Group ( *.DsnWrk). In the Projects panel, the entry of the current Project Group – either the default one (Project Group 1.DsnWrk), or one you have created or opened – is shown with the  icon.

This can be of particular advantage when the set of projects is related or linked, such as a product design that is composed of multiple PCBs. Creating a Project Group that includes all the relevant projects allows you to open, manipulate, and save multiple projects as a single entity.

Notes on using project groups:

• The current Project Group is listed along with open projects in the Projects panel – either the default one (Project Group 1.DsnWrk), or one you have created or opened.
• To save the currently opened set of projects as a group select File » Save Project Group As from the main menu.

• To open an existing group, select File » Open Project Group from the main menu, or right-click in the panel and select Open Project Group from the context menu. Use the same access for the Save Project Group command.

  Attempting to open a Design Project Group that is already open will result in the Design Project Group being closed and reopened. You will be prompted to save any changes made to open documents.
• To save a project group, right-click on its entry in the Projects panel and choose the Save Project Group command, from the context menu.
• To save a copy of the currently active design Project Group in the Projects panel, with a new name (if required), and to a specified location on the hard disk, choose the File » Save Project Group As command from the main menus or right-click on its entry in the Projects panel and choose the Save Project Group As command from the context menu.
• To close a Project Group, select Window » Close All from the main menus.
• To close all documents in a Project Group, select Window » Close Documents from the main menus.
• To create a new Project Group, select File » New » Design Project Group from the main menu – this will load the default (blank) Project Group (Project Group 1.DsnWrk). The same method can be used to close the current Project Group file.
• Only one Project Group can be open at a time, so when opening a different Project Group the current group will close. You will be prompted to save any unsaved documents, projects or changes to the current group first.
• To add another project to a Project Group, open or create a project and then save the current Project Group. Alternatively, right-click in the panel and select the Add Existing Project option.

A set of related local projects as a Project Group

Opening Recent Documents, Projects and Project Groups

Recently closed documents, projects and project groups can be opened from any editor by using indexed commands of the File » Recent Documents, File » Recent Projects, or File » Recent Project Groups sub-menu, respectively. A list shows the most recently closed entities (up to a maximum of nine entities). Position 1 (at the top) reflects the last entity closed.

You can also choose the All Recent Documents and Projects command from any of these menus to open the Recent Documents, Projects and Project Groups dialog. The dialog lists all recently closed documents, projects, and design project groups conveniently within one location. Select what you want to open then either click OK to close the dialog and open your selection or Open Selected Documents to open your selection - keeping the dialog open for further selection. Use the standard Windows shortcuts (Ctrl+click and Shift+click) to select multiple items from the list.

Soft Delete

Flexible functionality is available for removing managed design items such as Projects, Components and Released data directly from within Altium Designer, from the Explorer panel. Operating as a 'soft delete', the removal process provides increased options and information as you proceed, including relevant links to source items for review purposes. In the Workspace, deleted items are moved to a dedicated Trash location, where they can be retrieved (Restore) or completely removed (Permanently Delete) from the Trash page of the Workspace's browser interface.

Soft delete in action. Here, a project is being deleted, along with its related release (if manufacturing packages had been created from any releases, those would also be deleted).