Working with Projects

Use Komodo's Project Manager to organize Komodo "components". Components are objects that are relevant to a project. For example, a project might contain all the components related to a specific software product: the product's source files, templates for creating new source files, snippets for adding repetitive sections of code, and run commands for building the output. By using projects to organize components, all the aspects of a project can be quickly accessed from a single location.

The top level of organization is the project file, which can contain files, folders and components like run commands and macros. Projects are XML files stored on disk with a ".kpf" extension. While these project files can be manually edited, it is unnecessary; all project maintenance can be performed within the Project Manager. If you manually edit the project file, make a backup copy first; invalid construction within a project file prevents it from loading.

Components within the Project Manager and the Toolbox are manipulated by an intuitive drag-and-drop interface, by context menus, or via the Project and Toolbox drop-down menus. Options for individual components are accessed via the Project drop-down menu, or via right-click context menus.

Use Komodo's sample project to become familiar with project functions.

Feature Showcases

Displaying the Project Manager

The Project Manager is displayed on a "tab" on the Right Pane of the Komodo workspace. It is displayed or hidden via any of the following methods:

  • View|Tabs|Projects: Use the View drop-down menu to modify Komodo's display characteristics.
  • Key Binding: The default key binding for opening and closing the Projects tab is 'Ctrl'+'Shift'+'P'. See Configuring Key Bindings to alter or view the current assignment.
  • Workspace Toolbar: If the Workspace Toolbar is displayed, click the "Show/Hide Left Pane" button. (Select View|Toolbars|Workspace to display the toolbar.) Alternatively, click the "Show Specific Tab" button and select Projects.

 

Creating Projects

Projects are created via any of the following methods:

  • File Menu: On the File menu, select New|New Project.
  • File Menu: On the File menu, select New|New Project From Template..., select the desired project template and click Open./li>
  • Project Menu: On the Project menu, click New Project.
  • Project Menu: On the Project menu, click New Project From Template..., select the desired project template and click Open.
  • Project Manager: New Project Button: On the Projects tab, click the New Project button.

When creating a new project, you are prompted to select a directory where the project file is stored. The project filename becomes the project name displayed in the Project Manager (without the ".kpf" extension).

Live Import

The Live Import option in Project Properties and Settings (set globally in Komodo under Edit|Preferences|Directory Import) makes the project behave as a Live Folder. A new project created with Live Import enabled contains the current contents of the filesystem directory in which it is created.

 

Opening Projects

Existing projects are opened by any of the following methods:

  • File|Open Menu: Select File|Open|Project.
  • Project Menu: Select Project|Open Project
  • Project Manager: On the Projects tab, click the Open Project button.

Recently opened projects can be accessed from the Komodo Start Page, or from the File|Recent Projects menu. (The number of recently opened projects is determined by the Most Recently Used preference.)

The project name and associated files are displayed on the Projects tab. Opening a project only opens the project file, not the components associated with the project.

 

Setting the Active Project

Multiple projects can be open at the same time. Components in any open project can be used. However, only one project at a time is "active". The active project is displayed in bold text. When the Add Component button in the Project Manager is invoked, the component is added to the active project, regardless of the project that is currently highlighted.

Knowing which project is currently active is important because file preferences can be stored in projects. Komodo chooses a location for saved preferences based on the following criteria:

  • When debugging a file in the active project, preferences are stored in the active project.
  • When debugging a file in a project which is open but not active, preferences are stored in the first project found containing that file.
  • When debugging a file that is not in an open project, preferences are saved as a 'global' preference for that file.

To set the active project, right-click the desired project name and select Make Active Project, or select Project|Make Active Project from the drop-down menu.

 

Adding Components to Projects

Projects are organization containers for "components". Components are items like files, folders, snippets, macros, etc. For information about individual components, refer to the relevant section of the documentation for the specific component.

Filesystem-based components consists of items that exist as entities on the disk: files, dialog projects and templates. Komodo-specific components exist only in Komodo, and are not stored as external disk entities. Komodo-specific components include open shortcuts, folders, snippets, run commands, URL shortcuts, macros and custom menus and toolbars.

Within projects, filesytem-based components are merely references; they cannot be moved or deleted from within Komodo; moving them between projects and the Toolbox, or deleting them from projects or the Toolbox, has no effect on their actual disk-based location or their contents. On the other hand, Komodo-specific components (such as macros and snippets) do not exist outside of Komodo; therefore, they can be moved and copied (for example, from the Toolbox to the Project Manager) and deleted independently of the filesystem.

For example, when a snippet (a Komodo-specific component) is copied from the Project Manager to the Toolbox, a new copy of the snippet is created; the original version still exists in the original location. Subsequent modifications of the snippet in the Toolbox do not change the version of the snippet stored in a project. On the other hand, when the contents of a file (a filesystem-based component) are changed, the changes apply regardless of the location from which the file is invoked.

To add a component to a project:

  • Project|Add: Use the Project drop-down menu. If multiple projects are open, the component is added to the project that is currently active.
  • Project|Add|project_name: When a project name is selected in the Project Manager, the selected project's name is also displayed in the Project drop-down menu. Components can be added directly to that project.
  • Add Button: Use the Add button on the Project tab. If multiple projects are open, the component will be added to the project that is currently selected.
  • Context Menu: Right-click a project name and select Add|component.
  • Drag and Drop: Drag and drop components from:
    • Drag-and-Drop-Aware Applications: Filenames can be dragged from drag-and-drop applications (such as Windows Explorer).
    • Project Manager or Toolbox: Components can be dragged between projects, the Toolbox and container components (such as folders).
    • Editor File Name Tabs: When a file is open in the editor pane, drag and drop from the tab that displays the filename to a project.
  • Import from Filesystem: Right-click a project and select Import from File System.
  • Cut/Copy/Paste: All components have a right-click menu that includes the options Cut, Copy and Paste. Use these options to move components between projects, the Toolbox and container components.

Some components have special component-specific mechanisms for being added to projects. For example, snippets can be created and added to a project in one step by selecting a block of text in the Editor Pane and dragging it onto a project. URL shortcuts are created by dragging and dropping a URL from a browser address bar or from the Editor Pane onto a project. Refer to the specific component sections for more information about these options.

To remove a component from a project, click the desired component and press 'Delete', or right-click the component and select Delete from the context menu.

Komodo-specific components (such as run commands, macros, etc) are permanently deleted. Filesystem-based components (such as files and dialog projects) are not; only the reference to the component within the project is removed.

 

Project Display Settings

Use the button on the top right of the Project Manager to select the fields that are displayed in the Project Manager. Click the column headings to organize the items according to the contents of any column.

Column contents depend on the type of component. For example, the Status and Depot Rev display options only have contents if the component is part of a source code control repository.

The following columns can be displayed:

  • Date: The date from the filesystem when the component was last saved.
  • Size: The filesystem size of the component.
  • Status: The source code control status of the component.
  • Rev: When a component is part of a source code control repository, this column displays the revision number of the local version of the file.
  • Depot Rev: When a component is part of a source code control repository, this column displays the revision number of the repository version of the file.
  • Action: When a component is part of a source code control repository, this column displays the current action (if any) being performed on the file. For example, if a file is currently opened for editing, the action is "edit".
  • Name: The name of the component. For filesystem-based components (such as files and dialog projects), the name is equivalent to the filename. For Komodo-specific components (such as macros and run commands), the name is the user-defined name assigned to the component.

 

Saving Projects

If an asterisk is displayed beside the project name, the project has changed since it was opened or last saved. This happens not only when components are added, edited or removed in the Project Pane, but also when debugging options are changed for files in the project. To save a project:

  • File Menu: On the File menu, click Save Project.
  • Project Menu: On the Project menu, click Save Project. This saves the active project. If a project name is currently highlighted in the Project Manager, the Project menu contains an option for saving the selected project (Project|project_name|Save Project).
  • Project Manager: Save Project Button: On the Projects tab, click the Save Project button.
  • Project Context Menu: Right-click the desired project and select Save Project.

The mechanisms described above can also be used to save a project to a new project file by selecting Save Project As... rather than Save. Filesystem-based components (such as files and dialog boxes) are relative references rather than actual entities; in the new project, the reference to the location of the component is preserved. Komodo-specific components (such as macros and run commands) are copied to the new project; there are independent versions of the component in the original project and in the new project.

 

Refreshing Project Status

The Refresh Status option checks read/write disk status for the project file and for filesystem-based components (such as files and dialog projects) within the project. If the project contains files of a language for which "code intelligence" is supported and enabled (as configured in the Code Intelligence Preferences), Refresh Status also updates the code intelligence database with the contents of those files.

If the project or its components are stored in a source code control system, Refresh Status also checks the repository status of the file. Komodo determines whether a file is contained in an SCC repository by the following methods:

  • Perforce: query of the P4 repository (with the current user's client spec)
  • CVS: analysis of the CVS control directories
  • Subversion: analysis of the subversion control files

 

Importing and Exporting Projects via Packages

Entire projects (including all the components contained in a project) can be exported to a "package" file for distribution to other Komodo users or for the sake of archiving. Packages are compressed archive files that contain the project from which the Export Package option was invoked. The Export Package option differs from the Export as Project File option (provided for project components) in that Export Package creates a self-contained archive file that contains copies of all the filesystem-based components (such as files and dialogs). Export as Project File, on the other hand, only contains Komodo-specific components (such as snippets and run commands).

To export a project and its contents to an archive, select Project|project_name|Export Package from the drop-down menu, or right-click the project and select Export Package.

The Package Export Wizard prompts for a Package Name and a Export Location. The Package Name is the file in which the package is stored; it will have the extension ".kpz", and can be opened by any archiving utility that supports libz (for example WinZip).

Exported packages can only be imported into "container" objects in Komodo, such as projects, the Toolbox, and folders within projects and the Toolbox.

To import the contents of a package into a project, right-click the project to which you want to import the package, and click Import Package. The Package Import Wizard prompts for the name of the package and the location on disk where the files will be extracted. Click Next and then click Finish to complete the import.

For information about importing packages to the Toolbox or a folder, see Toolbox - Import Package and Folders - Import Package for more information.

 

Importing Files from the File System

This option creates files within a project based on the directory structure and file contents of a local or network filesystem. File references within the project are created for imported files; folders are created for directories (depending on the configuration of the import options). To import a filesystem into a project:

  • Project Menu: On the Project menu, click Import from File System. This imports the specified filesystem (according to the criteria described below) into the current active project. If a project name is currently highlighted in the Project Manager, the Project menu contains an option for importing into the selected project (Project|project_name|Import from File System).
  • Project Context Menu: Right-click the desired project and select Import from File System.

Configure the following import options:

  • Directory to import from: Specify the directory from which you want to import files. Use the Browse button to navigate the file system.
  • Browse for directory location: Choose Locally... to browse the local filesystem or Remotely... to browse a remote filesystem.
  • Files to include: Specify the filenames to include. Use wildcards ("*" and "?") to specify groups of files. Separate multiple file specifications with semicolons. If the field is left blank, all files in the specified directory are imported.
  • Files and directories to exclude: Specify the file and directory names to exclude. Use wildcards ("*" and "?") to specify groups of files. Separate multiple file specifications with semicolons. If the field is left blank, no files in the specified directory are excluded.
  • Import Subdirectories Recursively: Select this check box to import directories (and files contained in those directories) located beneath the directory specified in the Directory to import from field. This check box must be checked in order to specify the "Import Directory Structure" option as the Type of folder structure to create.
  • Type of folder structure to create:
    • Import directory structure: If the Import Subdirectories Recursively box is selected and this option is selected, Komodo creates folders within the project that represent imported directories. Thus, the directory structure is preserved within the project.
    • Make a folder per language: If this option is selected, imported files are organized into folders according to the language indicated by file pattern in the filename. File associations are configured in the Komodo Preferences. Each folder is named after the associated language, for example, "Perl files", "XML files", etc. Files that don't correspond to a known file pattern are stored in a folder called "Other files".
    • Make one flat list: If this option is selected, all the imported files are placed directly under the project from which the Import from File System command was invoked.

 

Source Code Control

Source code control refers to projects and/or components stored in a source code control depot (such as a CVS or Perforce repository). There are two aspects to source code control within projects: source code control on the project file itself, and source code control on components contained in projects.

When Komodo integration with a source code control system is configured, icons in the Project Manager display the SCC status of the project file and components contained in the project. See file status icons in the source code control documentation for more information about these icons.

Source code control functions (such as adding files to an SCC repository, or opening files contained in a repository for editing) can be performed both on the project file, and on the components contained in the project. To access SCC commands for a project file:

  • Project Menu: Click the project name in the Project Manager, then select Project|project_name|Source Control).
  • Project Context Menu: Right-click the desired project and select Source Control.

To access SCC commands for the components contained in a project:

  • Project Menu: Click the project name in the Project Manager, then select Project|project_name|Source Control on Contents).
  • Project Context Menu: Right-click the desired project and select Source Control on Contents.

See Source Code Control Commands for a description of each of the commands.

 

Reverting Projects

If a project has been altered but has not been saved, use the Revert Project option to undo the changes. To access the Revert Project option:

  • Project Context Menu: Right-click the desired project and select Revert Project.
  • Project Menu: Select Project|Revert Project or Project|project_name|Revert Project. Project|Revert Project reverts the active project. If a project name is currently highlighted in the Project Manager, the Project menu contains an option for reverting the selected project (Project|project_name|Revert Project).

 

Closing Projects

Closing a project removes it from the Project Manager. To close a project:

  • File Menu: On the File menu, click Close Project.
  • Project Menu: On the Project menu, click Close Project. This closes the active project. If a project name is currently highlighted in the Project Manager, the Project menu contains an option for closing the selected project (Project|project_name|Close Project).
  • Project Context Menu: Right-click the desired project and select Close Project.

If the project has changed since it was last saved, you are prompted to save it. If files contained in the project are open in the editor, you are asked if you wish to close them.

 

Deleting Projects

When a project is deleted, the project file is deleted from disk; Komodo-specific components (such as run commands and macros) stored in the project are also deleted. Filesystem-based components (such as files and dialog projects) are not deleted. To delete a project, delete the project file from the filesystem.

 

Project Properties and Settings

The Project Properties and Settingsdialog box contains information about the project file, such as its size, its location on disk, its directory import settings, its source code control status, and project-specific language settings.

To access the Project Properties dialog box, right-click the desired project name and select Properties, or click the desired project and select Project|project_name|Properties from the drop-down menu.

The following categories are available:

  • Properties: Displays the name, size, and location of the project; the date and time it was created, last modified and last accessed; and indicates if the project is read-only.
  • Source Code Control: Displays SCC status as applicable (SCC System, Status, Depot Revision, and My Revision).
  • Directory Import: Defines how Komodo dynamically imports files and directories into the project. These settings override those configured in Komodo's global Directory Import preferences. Select the Live Import check box to keep the imported directories and files current with the file system via Live Folders.
  • Languages: Allows you to add additional directories to a language's path for Komodo to use when debugging, syntax checking, or in the interactive shell. Komodo will also scan these directories for Autocompletion and CallTips information.