Sign in Join
Wiki copytemporary

Project Templates: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: Project Templates

OldNewLine
1+# Overview
2+
3+You can adapt how to create new projects. The IDE allows to register your own project types via designtime packages. The package **projtemplates** (the normal lazarus binary packages have this preinstalled) allows to simply use existing projects as templates.
4+
5+# Package projtemplates
6+
7+This package implements project templates and comes with the lazarus sources (components/projecttemplates/projtemplates.lpk).
8+
9+The package comes preinstalled with the binary packages of Lazarus (e.g. the windows installer). This package adds a category to the **File-New** dialog: **Template projects**
10+
11+It also adds a **New project from Template** menu item to the **File** menu, as well as a **project template options** menu under the **Tools** menu. This menu item is visible only if the templates directory (see next paragraph) exists and contains at least one template subdirectory.
12+
13+In the *Project template options*, a directory can be selected. This directory should contain a subdirectory per template. Each template directory contains a template for a project: A collection of files which will be copied and used as a new project.
14+
15+During the copy, the package will scan the file/directory names and the contents of the files for variable substitution: **__VARNAME__** will be replaced by the value of a variable VARNAME
16+
17+By default, the engine knows 2 variables:
18+
19+- ProjDir: The directory where the new project will be created.
20+- ProjName: The name of the new project in ProjDir.
21+
22+Additional variables must be defined in a file called **project.ini** in the directory of the project template. This is a file in Windows INI format.
23+
24+The section *\[Variables\]* will be scanned for variable names:
25+
26+``` ini
27+ [Variables]
28+ VarName1=Description 1[|DefaultValue 1]
29+ VarName2=Description 2[|DefaultValue 2]
30+```
31+
32+The variables found will be presented with their description in a dialog, and the user must present a value for the variables.
33+
34+The' 'project.ini*file can contain a second section, called*Project'', which can contain some info about the project. The following keywords can be found there:
35+
36+## ProjectFile
37+
38+The filename (no extension) of the template project lpi-file. Any file that has a name equal to this (no extension) is treated specially, it is renamed to the new project name (ProjName). That is *ProjectFile=example* will replace *example.lpi*, *example.lpr* and *example.cfg* with the name given by the user. By default, the value of **ProjectFile** is assumed to be *project*. (note that the .ini file is not copied)
39+
40+ProjectFile is not mandatory. The first *.lpi file in the template project folder will be taken as ProjectFile if ProjectFile is not specified or doesn't exist.
41+
42+## Name
43+
44+Name of the template. The Name and description will be presented in the 'File-New' dialog.
45+
46+## Author
47+
48+Author of the template
49+
50+## Description
51+
52+Short (one-line) description of the project. The Name and description will be presented in the 'File-New' dialog.
53+
54+## Recurse
55+
56+A boolean value (1/0) which tells the engine to recurse in subdirectories or not.
57+
58+## Exclude
59+
60+Comma separated list of filename extensions which should not be searched for keyword subsitution.
61+
62+## Getting Started
63+
64+**Step 1:**
65+
66+Create your own template directory (for example ~/.lazarus/mytemplates) and set this path in Lazarus (menu: Tools -\> Project Template Options).
67+
68+**Step 2:**
69+
70+For any template functions to even appear in the Lazarus File menu, you will need at least one template which you can base on your existing (normal) project;
71+
72+\- Create a directory in your template directory (for example ~/.lazarus/mytemplates/myfirsttemplate)
73+
74+\- Copy your project files in this new directory (*.lfm, *.pas, *.ico, *.lpi, *.lpr, *.res)
75+
76+**Step 3:**
77+
78+Create a "project.ini" file in the new template directory.
79+
80+The minimum should look something like this:
81+
82+``` ini
83+ [Variables]
84+
85+ [Project]
86+ Name=My Form Template
87+```
88+
89+**Step 4:**
90+
91+Restart Lazarus to apply changes.
92+
93+*Optional:*
94+
95+The nice thing of Project Templates is that it supports variables. Since a project will probably not be named the same as your example template you will have to do some code editing and file renaming.
96+
97+**Files**:
98+
99+Rename the project file (ico, lpi, lpr, res) to __PROJNAME__.ext (where extension is the original extension of course). For example: project.lpi becomes __PROJNAME__.lpi. Note: the content of the lpi file might need some cleaning, for example removing history, reference to files, not sure if the lpi file is even needed.
100+
101+**File content**:
102+
103+For all files that referred to project.lpi etc., change the content of your files so all "project" references become "__PROJNAME__", e. g.:
104+
105+```text
106+ <Filename Value="project.lpr"/>
107+ <Filename Value="__PROJNAME__.lpr"/>
108+```
109+
110+You can optionally define your own variables, for example to give the "unit.pas" a different filename. You could define for example __MAINUNIT__ and __MAINFORM__ in project.ini as MAINUNIT and MAINFORM - during creation Lazarus will ask you for these names. Now every occurrence of __MAINUNIT__, for example, will be replaced with the text you provided (avoid special characters and spaces).
111+
112+Note that this works for all variables. Every occurrence of a variable in filenames and file content will be replaced by what you entered on creation of a new project based on your template. Predefined variables are PROJNAME and PROJDIR but I didn't find a purpose for PROJDIR just yet.
113+
114+**Some examples of a project.ini:**
115+
116+project.ini:
117+
118+``` ini
119+ [Variables]
120+ MAINUNIT=Filename for the default unit.pas file
121+ MAINFORM=Form name
122+
123+ [Project]
124+ Name=My Custom Form
125+ Author=Author's Name
126+ Description=Lazarus LCL form specifically for my needs
127+```
128+
129+__PROJNAME__.lpr:
130+
131+``` pascal
132+program __PROJNAME__;
133+
134+{$mode objfpc}{$H+}
135+
136+uses
137+ {$IFDEF UNIX}
138+ cthreads,
139+ {$ENDIF}
140+ {$IFDEF HASAMIGA}
141+ athreads,
142+ {$ENDIF}
143+ Interfaces, // this includes the LCL widgetset
144+ Forms, __MAINUNIT__
145+ { you can add units after this };
146+
147+{$R *.res}
148+
149+begin
150+ RequireDerivedFormResource:=True;
151+ Application.Scaled:=True;
152+ Application.Initialize;
153+ Application.CreateForm(T__MAINFORM__, __MAINFORM__);
154+ Application.Run;
155+end.
156+```
157+
158+__MAINUNIT__.pas:
159+
160+``` pascal
161+unit __MAINUNIT__;
162+
163+{$mode ObjFPC}{$H+}
164+
165+interface
166+
167+uses
168+ Classes, SysUtils, Forms, Controls, Graphics, Dialogs;
169+
170+type
171+ T__MAINFORM__ = class(TForm)
172+ private
173+
174+ public
175+
176+ end;
177+
178+var
179+ __MAINFORM__: T__MAINFORM__;
180+
181+implementation
182+
183+{$R *.lfm}
184+
185+end.
186+```
187+
188+__MAINUNIT__.lfm:
189+
190+``` pascal
191+object __MAINFORM__: T__MAINFORM__
192+ Left = 725
193+ Height = 366
194+ Top = 433
195+ Width = 503
196+ Caption = '__MAINFORM__'
197+ LCLVersion = '2.2.6.0'
198+end
199+```
200+
201+Keep in mind that this brief tutorial is just to get you started, the variable replacement mechanism offered can be utilized for many different purposes. For example to define a form caption, a copyright statement, a web link on your forms, specific objects, etc. --Hansaplast 16:30, 4 August 2012 (UTC)
202+
203+---
204+*From the Free Pascal wiki, page "Project Templates", as it stood on 2023-12-15 after a change by Mark Paley, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*

Back to history