Project Templates: what changed

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

Old	New		Line
1	1		# Overview
2	2
3	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	4
5	5		# Package projtemplates
6	6
7	7		This package implements project templates and comes with the lazarus sources (components/projecttemplates/projtemplates.lpk).
8	8
9	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	10
11	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	12
13	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	14
15	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	16
17	17		By default, the engine knows 2 variables:
18	18
19	19		- ProjDir: The directory where the new project will be created.
20	20		- ProjName: The name of the new project in ProjDir.
21	21
22	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	23
24	24		The section \[Variables\] will be scanned for variable names:
25	25
26	26		``` ini
27	27		[Variables]
28	28		VarName1=Description 1[\|DefaultValue 1]
29	29		VarName2=Description 2[\|DefaultValue 2]
30	30		```
31	31
32	32		The variables found will be presented with their description in a dialog, and the user must present a value for the variables.
33	33
34	34		The' 'project.inifile can contain a second section, calledProject'', which can contain some info about the project. The following keywords can be found there:
35	35
36	36		## ProjectFile
37	37
38	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	39
40	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	41
42	42		## Name
43	43
44	44		Name of the template. The Name and description will be presented in the 'File-New' dialog.
45	45
46	46		## Author
47	47
48	48		Author of the template
49	49
50	50		## Description
51	51
52	52		Short (one-line) description of the project. The Name and description will be presented in the 'File-New' dialog.
53	53
54	54		## Recurse
55	55
56	56		A boolean value (1/0) which tells the engine to recurse in subdirectories or not.
57	57
58	58		## Exclude
59	59
60	60		Comma separated list of filename extensions which should not be searched for keyword subsitution.
61	61
62	62		## Getting Started
63	63
64	64		Step 1:
65	65
66	66		Create your own template directory (for example ~/.lazarus/mytemplates) and set this path in Lazarus (menu: Tools -\> Project Template Options).
67	67
68	68		Step 2:
69	69
70	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	71
72	72		\- Create a directory in your template directory (for example ~/.lazarus/mytemplates/myfirsttemplate)
73	73
74	74		\- Copy your project files in this new directory (.lfm, .pas, .ico, .lpi, .lpr, .res)
75	75
76	76		Step 3:
77	77
78	78		Create a "project.ini" file in the new template directory.
79	79
80	80		The minimum should look something like this:
81	81
82	82		``` ini
83	83		[Variables]
84	84
85	85		[Project]
86	86		Name=My Form Template
87	87		```
88	88
89	89		Step 4:
90	90
91	91		Restart Lazarus to apply changes.
92	92
93	93		Optional:
94	94
95	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	96
97	97		Files:
98	98
99	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	100
101	101		File content:
102	102
103	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	104
105	105		```text
106	106		<Filename Value="project.lpr"/>
107	107		<Filename Value="__PROJNAME__.lpr"/>
108	108		```
109	109
110	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	111
112	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	113
114	114		Some examples of a project.ini:
115	115
116	116		project.ini:
117	117
118	118		``` ini
119	119		[Variables]
120	120		MAINUNIT=Filename for the default unit.pas file
121	121		MAINFORM=Form name
122	122
123	123		[Project]
124	124		Name=My Custom Form
125	125		Author=Author's Name
126	126		Description=Lazarus LCL form specifically for my needs
127	127		```
128	128
129	129		__PROJNAME__.lpr:
130	130
131	131		``` pascal
132	132		program __PROJNAME__;
133	133
134	134		{$mode objfpc}{$H+}
135	135
136	136		uses
137	137		{$IFDEF UNIX}
138	138		cthreads,
139	139		{$ENDIF}
140	140		{$IFDEF HASAMIGA}
141	141		athreads,
142	142		{$ENDIF}
143	143		Interfaces, // this includes the LCL widgetset
144	144		Forms, __MAINUNIT__
145	145		{ you can add units after this };
146	146
147	147		{$R *.res}
148	148
149	149		begin
150	150		RequireDerivedFormResource:=True;
151	151		Application.Scaled:=True;
152	152		Application.Initialize;
153	153		Application.CreateForm(T__MAINFORM__, __MAINFORM__);
154	154		Application.Run;
155	155		end.
156	156		```
157	157
158	158		__MAINUNIT__.pas:
159	159
160	160		``` pascal
161	161		unit __MAINUNIT__;
162	162
163	163		{$mode ObjFPC}{$H+}
164	164
165	165		interface
166	166
167	167		uses
168	168		Classes, SysUtils, Forms, Controls, Graphics, Dialogs;
169	169
170	170		type
171	171		T__MAINFORM__ = class(TForm)
172	172		private
173	173
174	174		public
175	175
176	176		end;
177	177
178	178		var
179	179		__MAINFORM__: T__MAINFORM__;
180	180
181	181		implementation
182	182
183	183		{$R *.lfm}
184	184
185	185		end.
186	186		```
187	187
188	188		__MAINUNIT__.lfm:
189	189
190		-	~~``` pascal~~
	190	+	``` lfm
191	191		object __MAINFORM__: T__MAINFORM__
192	192		Left = 725
193	193		Height = 366
194	194		Top = 433
195	195		Width = 503
196	196		Caption = '__MAINFORM__'
197	197		LCLVersion = '2.2.6.0'
198	198		end
199	199		```
200	200
201	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	202
203	203		---
204	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