Multiple Lazarus: what changed

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

Old	New		Line
1	1		## Multiple Lazarus instances
2	2
3	3		You can have one directory with Lazarus in it on your system or more. These directories can contain the same or different versions of Lazarus and can be made to work independent of each other (see the section dealing with --primary-config-dir below). Because you don't have to install Lazarus and the versions may be the same, the concept of having more than one Lazarus directory on your system will be called "multiple instances" in this article.\
4	4		Runthrough for Linux at [[DualLaz]].
5	5
6	6		## Important
7	7
8	8		- Make Backups of
9	9		- Your primary config (e.g. ~/.lazarus under Unix)
10	10		- Your projects .lpi and .lps
11	11
12	12		## Who needs multiple Lazarus instances and who does not?
13	13
14	14		You need multiple Lazarus instances...
15	15
16	16		- to have several versions of Lazarus
17	17		- to have one Lazarus version compiled with several different versions of [[FPC]]
18	18
19	19		You don't need multiple instances...
20	20
21	21		- to test your project with different [[Widgetset\|widgetsets]]
22	22		- to [[Cross compiling\|cross compile]]
23	23
24	24		## The Lazarus directory
25	25
26	26		The Lazarus directory (i.e. the directory where the Lazarus application is) is overridable using --lazarusdir, this is useful when running Lazarus from e.g. USB sticks with varying mountpoints or driveletters.
27	27
28	28		## The config directory
29	29
30	30		All IDE options for an instance are saved to a config directory. Under Linux, macOS and BSD the default config directory is ~/.lazarus. Note the beginning dot, which makes it a hidden directory.
31	31
32	32		On Windows, settings are saved to the User AppData folder, which maps to a different directory depending on the Windows version (and language, in Windows XP and earlier). See also information here: Windows. Note that you won't see the configuration directory in Windows unless you select to see hidden and system files. To view the directory, type:
33	33
34	34		```dos
35	35		%localappdata%
36	36		```
37	37
38	38		in the Start/Run box or in the address bar of Windows Explorer, which should bring you to the Local Application Data directory. For default installs, the settings are stored in the Lazarus directory shown there.
39	39
40	40		\| Operating System \| Default location for the config directory \| Remarks \|
41	41		\|----\|----\|----\|
42	42		\| Linux, macOS, BSD, other UNIXes \| ~/.lazarus \| Hidden directory \|
43	43		\| Windows XP \| C:\Documents and Settings\\\<User name\>\Local Settings\Application Data\lazarus \| English Windows; others may have different paths \|
44	44		\| Windows Vista and higher \| C:\Users\\\<User name\>\AppData\Local\lazarus\\ \| Regardless of selected language \|
45	45
46	46		The config directory can not be shared between different Lazarus versions. A newer Lazarus can read older configs and will update them automatically. There is no guarantee that an older version can read config files of a newer version. It is always a good idea to make a backup of your configs from time to time for time you might’ve change something weird and not know what it was.
47	47
48	48		### Solution for separating instances using multiple config dirs
49	49
50	50		The config directory can be given on the command line with the --primary-config-path parameter (shorter version: --pcp). For example:
51	51
52	52		``` bash
53	53		lazarus --primary-config-path=~/.lazarus2
54	54		```
55	55
56	56		will start an IDE using ~/.lazarus2 as config directory. This way you can have an arbitrary number of config directories and start several independent Lazarus instances. As Lazarus creates the settings files from default if they don't exist, you can specify empty directories if you want.
57	57
58	58		If you use this often, then a small shell script can be created:
59	59
60	60		``` bash
61	61		#!/bin/sh
62	62		/path/to/lazarus --primary-config-path=~/.lazarus2
63	63		```
64	64
65	65		In Windows you cannot use ~ so use instead, for example, a shortcut on the desktop with the following parameters to call Lazarus:
66	66
67	67		``` bash
68	68		\path\to\lazarus.exe --primary-config-path=lazarusconf
69	69		```
70	70
71	71		This will place the lazarus configuration directory inside the lazarus directory.
72	72
73	73		### Using lazarus.cfg file
74	74
75	75		Another way for setting config directory is using a “lazarus.cfg" file and putting it into the folder with the Lazarus executable and putting this line into it :
76	76
77	77		``` bash
78	78		--primary-config-path=\path\to\config\folder
79	79		```
80	80
81	81		You can make a config folder any where you like and set it's path to the cfg file. After that Lazarus will use this lazarus.cfg file and there is no need to make a shell script or use shortcut file with the —-pcp parameter.
82	82
83	83		For example, for a Windows installation it will be like this : A config folder and a lazarus.cfg file near the Lazarus executable and put a value like this for example into the cfg file :
84	84
85	85		```Dos
86	86		--primary-config-path=C:\Lazarus2\config\
87	87		```
88	88
89	89		And run Lazarus. It will ask for some config values and after that you can make a simple shortcut for later use without any parameters.
90	90
91	91		### Config directory files
92	92
93	93		See the [[pcp\|Primary Config Path]] page.
94	94
95	95		lazarus.dci - stores the Lazarus Code Templates
96	96
97	97		editoroptions.xml - information about colors, fonts and other editor options
98	98
99	99		miscellaneousoptions.xml - packages information
100	100
101	101		environmentoptions.xml - stores the history of opened projects and files (Recent Opened Files and Projects)
102	102
103	103		## The Lazarus files
104	104
105	105		The Lazarus source archive is contained in a single directory. You can simply compile Lazarus (eg, for [[Installing Lazarus on Linux\|Linux]] or for [[Installing Lazarus on Windows\|Windows]]) and a lot of files and subdirectories will be created, but and all will be below that single subdirectory.
106	106
107	107		A Lazarus instance (sources and resources) is a single subdirectory. Just copy this directory and you get a whole new Lazarus instance.
108	108
109	109		You don't need to install Lazarus to be able to run it. But if you do indeed install Lazarus, you get some nice shortcuts on your desktop and some file types (e.g. lpk, lpi, pas) are associated with that Lazarus installation. These things are platform dependent. You can have only one formally installed Lazarus but secondary installs work just as well, typically you will start the one you want with a script or cd-ing to its own directory and starting it there. A formal install is typically added to your PATH so care might be needed, when using a secondary copy, that you don't get the 'on path' executable, some users prefer to have no formally installed copies for that reason, Lazarus, built from source works fine from its source directory.
110	110
111	111		Newer installers support installing Lazarus multiple times. Alternatively, You can also add another Lazarus instance manually quite easily. Of course, file associations etc. can only be linked to one single Lazarus instance.
112	112
113	113		### Linux
114	114
115	115		See the instructions for [[Installing Lazarus on Linux\|Installing Lazarus from Source]] and repeat that as many times, each in a new directory, as you like. It often makes sense to use your distro provided version of FPC (as long as its up to date) and build your Lazarus from source. Don't bother to "install" Lazarus, its fine to just have it all in your own file space, cd into the desired directory and launch lazarus from the command line. Just make sure each Lazarus directory has its own config directory (and knows how to find it).
116	116
117	117		If you do decide to have one or more Lazarus "installs", its a good idea not to have a package installed version as well. They tend to cause some PATH confusion.
118	118
119	119		Find a 2015 run-through for Linux 64 bit at [[DualLaz]].
120	120
121	121		#### Example 1 : A normally installed Lazarus instance plus the git version
122	122
123	123		Download and install the Lazarus debian- & .rpm - packages as normal.
124	124
125	125		Then download the Lazarus git archive to a directory of your choice, preferably somewhere in your home directory (e.g. ~/lazarus). See here [[Getting Lazarus\|Getting Lazarus from the GitLab server]].
126	126
127	127		Start your secondary Lazarus with:
128	128
129		-	~~`/home/you/lazarus/startlazarus --pcp=~/.lazarus2nd`~~
	129	+	```text
	130	+	/home/you/lazarus/startlazarus --pcp=~/.lazarus2nd
	131	+	```
130	132
131	133		#### Example 2 : A normally installed Lazarus instance plus a manual copy
132	134
133	135		i.e. you obtain two subdirectories:
134	136
135		-	~~`/usr/lib/lazarus original copy via debian install`\~~
136		-	~~`/home/you/lazarus secondary copy `~~
	137	+	```text
	138	+	/usr/lib/lazarus original copy via debian install
	139	+	/home/you/lazarus secondary copy
	140	+	```
137	141
138	142		or you may look at:
139	143
140		-	~~`/home/you/development/lazarus original copy via fpcUP install`\~~
141		-	~~`/home/you/lazarus secondary copy `~~
	144	+	```text
	145	+	/home/you/development/lazarus original copy via fpcUP install
	146	+	/home/you/lazarus secondary copy
	147	+	```
142	148
143	149		Download and install the Lazarus debian-packages as usual.
144	150
145	151		Then copy the Lazarus directory to your home directory and change the ownership of the files:
146	152
147	153		``` bash
148	154		cp -a /usr/lib/lazarus $(HOME)/
149	155		chown $USER:$USER -R $(HOME)/lazarus
150	156		```
151	157
152	158		(Note: The chown line assumes that your group has the same name as your username. If not, replace \$USER:\$USER with your username:groupname)
153	159
154	160		Now change your Lazarus desktop/menu shortcut to start the secondary copy
155	161
156		-	~~`/home/you/lazarus/startlazarus --pcp=~/.lazarus2nd`~~
	162	+	```text
	163	+	/home/you/lazarus/startlazarus --pcp=~/.lazarus2nd
	164	+	```
157	165
158	166		Then start the IDE and change the environment options: Tools -\> Options -\> Environment / Lazarus directory to the secondary subdir, namely /home/you/lazarus
159	167
160	168		In recent Lazarus versions, you are also given a screen to name the other important paths, so you would name the secondary sudirs in the 2ndary config.
161	169
162	170		Also, inside the /home/you/development/fpc/bin/x86_64-linux/fpc.cfg text file, all paths should rather point to your secondary copy. To make sure everything is fine, run startlazarus from within xterm and watch the errormessages. make sure all paths are found (very difficult currently).
163	171
164	172		You now have a secondary copy that which you can edit and recompile. Don't forget to close source files of the primary /usr/lib/lazarus.
165	173
166	174		### Windows
167	175
168	176		#### Example 1: GIT and Release
169	177
170	178		This is to have both GIT and last release version of Lazarus.
171	179
172	180		1\) Install Lazarus last release and check setup option 'create desktop shortcut', you will get 'Lazarus.lnk' on the desktop.
173	181
174	182		2\) Get Lazarus from GIT and compile, then create a shortcut on your desktop for 'lazarus.exe' and rename it to 'Lazarus GIT.lnk'.
175	183
176	184		Then you can set the config dir for each version editing the shortcut path to the executable:
177	185
178	186		This is for release, because you don't change the primary config path parameter, the config will be saved in the default path:
179	187
180	188		```dos
181	189		C:\lazarus\startlazarus.exe
182	190		```
183	191
184	192		For GIT, store the settings e.g. in the folder 'C:\lazgitcfg\\':
185	193
186	194		```dos
187	195		C:\FPC\laz\startlazarus.exe --primary-config-path=C:\lazgitcfg
188	196		```
189	197
190	198		## Installation of multiple Lazarus
191	199
192	200		### Windows - Using the installer
193	201
194	202		On Windows the installer (Version 1.1) can create a secondary installation. And it will ask for a folder to store the config.
195	203
196	204		- Install:
197	205		- Make sure you back up ALL your existing configurations BEFORE you install.
198	206		- AGAIN: Make sure you back up ALL your existing configurations BEFORE you install.
199	207		- After install check that the correct config is used\
200	208		See the file "lazarus.cfg" in the installation directory. And Menu "View" \> "IDE Internals" \> "About IDE"
201	209		- If you see a message about upgrading/downgrading the config, then the installation is incorrect. Press "Cancel"
202	210		- Usage
203	211		- Do not share packages between installations; rather you must have several independent copies of each package
204	212		- Backup lpi and lps files (if you share projects). Ideally store sessions (lps) in the "IDE config directory"\
205	213		Menu: "Project" \> "Project Options" \> Session
206	214		- Uninstall:
207	215		- If you plan to uninstall: back up everything again
208	216		- Update:
209	217		- If you plan to update, back up everything again
210	218		- After updating, check that the correct config is still being used\
211	219		See the file "lazarus.cfg" in the installation directory. And Menu "View" \> "IDE Internals" \> "About IDE"
212	220
213	221		The Windows Installer is able to create secondary installations, which allows you to have different versions installed that do not interfere with each other.
214	222
215	223		All you need to do is tick the checkbox "secondary installation" (when choosing the install directory), and follow the instructions. You will then be asked for a new empty folder where the config will be stored (this can be a subfolder in the install directory).
216	224
217	225		If you update an installation using the Windows Installer, it will detect when the selected directory contains a secondary install.
218	226
219	227		In order to always be able to quickly see which IDE you are using, and also to check that the correct config is loaded, it is advisable to make changes to some visual attributes. A possibility is to change the gutter color in the editor.
220	228
221	229		#### Windows - Adding a cross compiler install
222	230
223	231		The installation packages for cross compilers can be added to secondary installations, too. However, they will currently give a warning that the folder is not empty. This warning can be ignored.
224	232
225	233		# Visually distinguish
226	234
227	235		To distinguish each Lazarus visually you can:
228	236
229	237		- Set a different color for the gutter - the left column of the source editor where the line numbers and break points are shown.
230	238		- Set the title of the IDE
231	239
232	240		---
233	241		From the Free Pascal wiki, page "Multiple Lazarus", as it stood on 2023-11-08 after a change by Dbannon, 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