Unit not found - How to find units: 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		This page is about the most dreaded, prominent error of Pascal: unit not found or can't find unit.
4	4
5	5		This error has a lot of potential reasons, so this page attempts to gather most of those, plus how to identify which particular problem it is and how to hopefully solve it. Usually, under this condition, Lazarus does not compile any program at all nor does it recompile the IDE any longer, meaning Lazarus is completely "broken" until the fix is applied.
6	6
7	7		> Note: Lazarus provides a tool to test for many common misconfigurations: The button Project Options / Test. Click these and see the warnings it produces. Normally it will only warn (safely ignore those) about certain duplicate ppu files in the fpc sources (the actual file dupes depend on the fpc version and distribution).
8	8
9	9		## Quick list
10	10
11	11		For experts here is a list of possible causes for the error. This list is not sorted for probability.
12	12
13	13		- FPC installation
14	14		- You named one of your units like one of the FPC units.
15	15		- Wrong fpc.cfg. \$HOME/.fpc.cfg instead of /etc/fpc.cfg. Find out with -vut.
16	16		- Missing or wrong search path in fpc.cfg. Find out with -vut.
17	17		- Added a search path to fpc.cfg that contains sources (.pas,.pp)
18	18		- Cross compiling: Forgot to install the cross compiled FPC ppus. Find out with -vut.
19	19		- Broken FPC installation. Remove FPC directory manually and install again.
20	20		- Compiler symlink points to wrong compiler.
21	21		- subcase: 2 compilers in searchpath, see: [[install on Linux cheatsheet]]
22	22		- FPCDIR environment variable is set
23	23		- You named one of your include files like one of the FPC include files and your FPC installation was not compiled with -Ur.
24	24		- Specific [problem](https://stackoverflow.com/a/64637024/1020550) of Ubuntu installations
25	25		- Lazarus
26	26		- Forgot to add a package dependency. Check project inspector or package editor.
27	27		- A ppu exists twice. Find out with -vut. Remove the wrong ppu. Check if a package usage unit paths is only \$(PkgOutDir) and the usage include path is empty. Check if two packages or a package and the project contain the same unit search path in their compiler options.
28	28		- Typo or missing search paths. Check Project / Project Options / Compiler Options, pages Paths and Inherited and check source editor / popup menu / file settings / unit info / unit paths.
29	29		- Wrong case. If the unit filename uses upper and lower case letters all uses sections must use the correct case. Before 0.9.29 the IDE did not search 'in' filenames in lower and upper case. Check that the 'in' filenames in uses sections.
30	30		- Wrong unit: If there are two units with the same name in the search path the compiler may use the wrong one without warning. The IDE normally warns unless disabled in Tools / Options / Environment / Naming / ambiguous file action.
31	31		- Forgot to install the FPC sources and/or forgot to set the path in Tools / Options / Environment / Files / FPC source directory.
32	32		- Using the wrong version of FPC sources
33	33		- Using the wrong compiler. Check Tools / Options / Environment / Files / compiler path. Also click "project options / Test" to diagnose for this condition
34	34		- Using the wrong lazarus directory. Check Tools / Options / Environment / Files / Lazarus directory.
35	35		- Added a search path to your own units to fpc.cfg instead of creating a package.
36	36		- Cross compiling: Forgot to cross compile lcl, synedit for the new platform. These are not compiled automatically (They are since 0.9.31).
37	37		- Wrong package: you have a package (.lpk) twice on your disk and the IDE is still using the old
38	38
39	39		## Notations, terms
40	40
41	41		- .pas file: This is a place holder for any pascal unit source. For example unit1.pas or unit1.pp. Both extensions are allowed and there is no difference. There are other compilers, which ignore .pp files, but this page is about the Free Pascal compiler.
42	42		- .pp file: Same as .pas. Just another extension for the same thing.
43	43		- .p file: Same as .pas. Just another extension for the same thing. Commonly utilized on Macintosh.
44	44		- .ppu file: This is place holder for any compiled pascal unit, created by the Free Pascal compiler.
45	45
46	46		## Step 1: Compiler or IDE or both
47	47
48	48		The IDE and the compiler do not use the exact same way to locate units.
49	49
50	50		### Compiler
51	51
52	52		If the compiler can not find it, the compilation fails (Build, Ctrl+F9) with the error 'unit not found'.
53	53
54	54		### IDE
55	55
56	56		If the IDE can not find, the codetools will fail. For example Find Declaration (Alt+Up or Ctrl+Left mouse button) or Identifier completion (Ctrl+Space) will fail with the error 'unit not found'. If the error message is about units you don't use directly, then simply add the unit name to a uses section and do a find declaration. After that you can remove it.
57	57
58	58		### Search strategies
59	59
60	60		#### What both search
61	61
62	62		- Both search units in the search path.
63	63		- Both search first for pascal sources (.pas, .pp) files. Under MacPAS mode: search for .p files too.
64	64		- Both search for several cases: normal case, lower case, upper case. For example: if the uses section contains 'Unit1', then it searches:
65	65
66		-	~~` 1. Unit1.pp`\~~
67		-	~~` 2. unit1.pp`\~~
68		-	~~` 3. UNIT1.PP`\~~
69		-	~~` 4. Unit1.pas`\~~
70		-	~~` 5. unit1.pas`\~~
71		-	~~` 6. UNIT1.PAS`~~
	66	+	```text
	67	+	1. Unit1.pp
	68	+	2. unit1.pp
	69	+	3. UNIT1.PP
	70	+	4. Unit1.pas
	71	+	5. unit1.pas
	72	+	6. UNIT1.PAS
	73	+	```
72	74
73	75		They are searched in every directory of the search path.
74	76
75	77		#### Differences between IDE and FPC unit search
76	78
77	79		- FPC uses the fpc.cfg for additional search paths. The IDE uses them only to find files of the FPC sources. So adding a search path to the fpc.cfg is ignored by Lazarus.
78	80		- FPC always starts in one directory and every relative filename is relative to this directory. For the Lazarus IDE each project and each package has its own base directory. So the search path of a package is relative to the package directory. The package directory is the directory of the .lpk file. The base directory of a project is the projects main source file (e.g. the .lpr file). If there is no main source file, the directory of the .lpi file is taken. Normally both are the same and the IDE has no graphical frontend to split. But by editing the .lpi file manually you can split them. At the moment there is only one prominent example for this case: the ppxxx.lpi files of the Free Pascal compiler.
79	81		- FPC and Lazarus have different macros.
80	82		- You can define additional source search paths for the IDE, which are not given to the compiler. (Compiler options -\> Other source files)
81	83
82	84		## Case 1: Both can not find a unit
83	85
84	86		- Check if the unit exists: If not, then see chapter Searching packages, projects of a unit (ToDo: write me).
85	87		- Check if the unit is readable: (You can open it in the IDE). A unit source does not need to be writable. If not, then fix the permissions or get a readable copy.
86	88		- Check if the unit has a valid pascal name: (identifier plus extension). Valid examples: unit1.pas, Bogus2.pp, _1.pas, LAZ.PAS. Wrong examples: 1.pas (starts with number), a%.pas (contains special character), unit.PAS (extension uppercase, but filename lowercase).
87	89		- Check if directory name contains special characters
88	90
89	91		1. slashes / and backslashes \ are used as directory delimiter and should never be used for directory names
90	92		2. Semicolons are used to separate paths in the IDE.
91	93		3. dollar $ is used for macros in many scripting languages
92	94
93	95		- Check for right case: If your unit name is all lowercase or all uppercase you don't need to worry. If not, then you must make sure, that every uses section in every source code uses exactly this case. For example: if your unit is named Unit1.pas, then every uses section must use Unit1. This is not so important under windows, but under any other platform (Linux, MacOSX). The IDE gives warnings when saving files with mixed case.
94	96		- Check if the unit is in the search path. If the compilation stopped while compiling a package, look in the compiler options of that package (open the package, there is a button 'compiler options'). If the compilation stopped while compiling the project, look in the project / compiler options.
95	97
96	98		## Case 2: Compiler finds a unit, but IDE does not
97	99
98	100		The next sub cases assumes, that Run -\> Build (Ctrl+F9) in the Lazarus IDE works, but Find Declaration fails with the error: unit not found. If unsure, check Case 1 as well.
99	101
100	102		- Check if the unit source exists: The IDE searches for pascal source (.pas, .pp) and ignores the .ppu files. The compiler can use a .ppu, but the Lazarus IDE not. This feature is planned, but there is no time frame.
101	103		- Check if unit directory was added to your fpc.cfg: The compiler uses all paths defined in the fpc.cfg file. The IDE does not read this file. Add the search path to the compiler options of your projects and/or packages.
102	104		- Check for macros and special compiler flags: The compiler understands the asterisk * character in search paths. The IDE treats this character as normal character. You can add the -Fu, -FU, -FE flags manually to the custom compiler flags in the lazarus IDE, but they are not parsed. Always use the right fields for options. The custom options are only for flags like the -D flag or uncommon compiler options, like new features of the unstable developer compiler.
103	105		- Rescan the FPC source directory: sometimes after a new/fresh install the IDE has problems finding the FPC sources. Selecting this option from the main menu (Environment/Rescan the FPC directory) might fix the problem.
104	106
105	107		## Case 3: IDE finds a unit, but compiler does not
106	108
107	109		This is the case, when Find Declaration finds the unit, but building (Ctrl+F9) fails.
108	110
109	111		There are two cases: Either the compiler didn't find anything, or it does not like, what it found. In both cases it returns the same error: unit xyz not found.
110	112
111	113		You can see where the compiler sarches and what it finds by adding the -vu -vt options (short: -vut). Beware: This gives easily thousands of lines of output. The -vut must be applied to the step, that creates the error. If it happens when compiling the project, enable the -vt in the compiler options of the project. If it happens when building a package, use the compiler options of the package. If it happens when building the IDE, use the Tools / Configure Build Lazarus / Advanced Build Options / Options. Then compile again. It will slow down the compilation. Then right click on on messages window and click on 'Copy all and hidden messages to clipboard'. Then paste it i the source editor. Now search for all places where the unit name is mentioned.
112	114
113	115		### Case 3.1: The compiler finds the .ppu file, but does not like it
114	116
115	117		This can happen, when the found .ppu file is older than a required unit (.pas, .pp or .ppu). For example if unit1 uses unit2 and unit2 was changed, then unit1 needs to be recompiled as well.
116	118
117	119		It can also happen, if you installed newer files without deleting the old ones. The compiler stops at the first found.
118	120
119	121		You can see, what the compiler finds and what is missing by giving the -vt command line switch. But this gives a lot of output and it is hard to read for newbies.
120	122
121	123		The easiest way is often to first recompile the packages and project clean (Build all). In case of the Lazarus sources itself: The configure build lazarus dialog has a button to setup all options for a clean build.
122	124
123	125		### Case 3.2: The compiler cannot find source (.pas, .pp) or .ppu file
124	126
125	127		In this case you have to extend the search path. The question is: add the .ppu directory or the source directory?
126	128
127	129		> Warning: If you add the wrong search path, it can happen, that the compiler will create multiple copies of files and you will later get the 'unit not found' error of Case 3.1.
128	130
129	131		Many projects and packages have distinct source directories (.pas, .pp) and output directories (.ppu). If a package has an output directory, then only this directory should be added to the search path of any depending project and/or package. The IDE will do this automatically. For example: Adding the LCL as dependency to your project adds two output directories to your unit search path. You can see this in Compiler Options -\> Inherited. Never add any other LCL directory to your search paths or you will get Case 3.1 errors.
130	132
131	133		- Check if the unit is in the compiler search path: The search path given to the compiler are the -Fu options of the command line parameters. You can see the options given to the compiler in Compiler Options -\> Show Options.
132	134
133	135		### Case 3.3: The wrong compiler is being used
134	136
135	137		Perhaps when cross compiling the correct cross .ppu is found, but the wrong compiler is used by lazarus (see [[install on Linux cheatsheet]]).
136	138
137	139		Lazarus uses the compiler specificied in the environment options. It is easy to forget to change the compiler, if you change the target CPU. Therefore it is recommended to set the compiler in the environment options to the fpc executable, which is a front end to the ppcXXX compiler backends. The fpc executable chooses the right ppcXXX compiler based on the -P parameter or the native pccXXX compiler if no such parameter is given. The drawback of using fpc instead of for example ppc386 directly, is that an extra process needs to be started (one for fpc and one for ppcXXX) which slows down compilation slightly, but this is hardly measurable.
138	140
139	141		Run lazarus from a text console (with startlazarus) so you an see the debugging output and look at the output generated when you compile.
140	142
141	143		It may look like this:
142	144
143		-	~~`TPkgManager.GetWritablePkgOutputDirectory APackage=DBFLaz 0.1.1 AnOutDirectory="/home/sam/.lazarus/lib/DBFLaz/powerpc-linux"`\~~
144		-	~~`TLazPackageGraph.CheckIfPackageNeedsCompilation No state file for JPEGForLazarus 1.0.1`\~~
145		-	`[TExternalToolList.Run] CmdLine="/usr/bin/ppc386 -S2cgi -OG1 -Ppowerpc -gl -vewnhi -l -Fu../../lcl/units/powerpc-linux/ -Fu../../lcl/units/powerpc-linux/gtk2/ -Fu../../packager/units/powerpc-linux/ -Fu. -FU/home/sam/.lazarus/lib/JPEGForLazarus/powerpc-linux/ -dLCL -dLCLgtk2 jpegforlazarus.pas" `\
146		-	~~`WorkDir="/usr/share/lazarus/components/jpeg/"`\~~
147		-	~~`Hint: Start of reading config file /etc/fpc.cfg`\~~
148		-	~~`Hint: End of reading config file /etc/fpc.cfg`\~~
149		-	~~`Warning: You are using the obsolete switch -OG`\~~
150		-	~~`Free Pascal Compiler version 2.3.1 [2007/12/10] for i386`\~~
151		-	~~`Copyright (c) 1993-2007 by Florian Klaempfl`\~~
152		-	~~`Target OS: Linux for i386`\~~
153		-	~~`Compiling jpegforlazarus.pas`\~~
154		-	~~`Compiling lazjpeg.pas`\~~
155		-	~~`PPU Loading /usr/share/lazarus/lcl/units/powerpc-linux/intfgraphics.ppu`\~~
156		-	~~`PPU is compiled for another processor`\~~
157		-	~~`Fatal: Can't find unit IntfGraphics used by LazJPEG`\~~
158		-	~~`GetMsgLineFilename Filename "lazjpeg.pas" not found.`\~~
159		-	~~`TExternalToolList.Run Exception: /usr/share/lazarus/components/jpeg/lazjpeg.pas(1,1) Fatal: Can't find unit IntfGraphics used by LazJPEG `~~
	145	+	``` pascal
	146	+	TPkgManager.GetWritablePkgOutputDirectory APackage=DBFLaz 0.1.1 AnOutDirectory="/home/sam/.lazarus/lib/DBFLaz/powerpc-linux"
	147	+	TLazPackageGraph.CheckIfPackageNeedsCompilation No state file for JPEGForLazarus 1.0.1
	148	+	[TExternalToolList.Run] CmdLine="/usr/bin/ppc386 -S2cgi -OG1 -Ppowerpc -gl -vewnhi -l -Fu../../lcl/units/powerpc-linux/ -Fu../../lcl/units/powerpc-linux/gtk2/ -Fu../../packager/units/powerpc-linux/ -Fu. -FU/home/sam/.lazarus/lib/JPEGForLazarus/powerpc-linux/ -dLCL -dLCLgtk2 jpegforlazarus.pas"
	149	+	WorkDir="/usr/share/lazarus/components/jpeg/"
	150	+	Hint: Start of reading config file /etc/fpc.cfg
	151	+	Hint: End of reading config file /etc/fpc.cfg
	152	+	Warning: You are using the obsolete switch -OG
	153	+	Free Pascal Compiler version 2.3.1 [2007/12/10] for i386
	154	+	Copyright (c) 1993-2007 by Florian Klaempfl
	155	+	Target OS: Linux for i386
	156	+	Compiling jpegforlazarus.pas
	157	+	Compiling lazjpeg.pas
	158	+	PPU Loading /usr/share/lazarus/lcl/units/powerpc-linux/intfgraphics.ppu
	159	+	PPU is compiled for another processor
	160	+	Fatal: Can't find unit IntfGraphics used by LazJPEG
	161	+	GetMsgLineFilename Filename "lazjpeg.pas" not found.
	162	+	TExternalToolList.Run Exception: /usr/share/lazarus/components/jpeg/lazjpeg.pas(1,1) Fatal: Can't find unit IntfGraphics used by LazJPEG
	163	+	```
160	164
161	165		The clues are these lines:
162	166
163		-	`[TExternalToolList.Run] CmdLine="/usr/bin/ppc386 -S2cgi -OG1 -Ppowerpc -gl -vewnhi -l -Fu../../lcl/units/powerpc-linux/ -Fu../../lcl/units/powerpc-linux/gtk2/ -Fu../../packager/units/powerpc-linux/ -Fu. -FU/home/sam/.lazarus/lib/JPEGForLazarus/powerpc-linux/ -dLCL -dLCLgtk2 jpegforlazarus.pas" `\
164		-	~~`...`\~~
165		-	~~`Target OS: Linux for i386`\~~
166		-	~~`...`\~~
167		-	~~`PPU Loading /usr/share/lazarus/lcl/units/powerpc-linux/intfgraphics.ppu`\~~
168		-	~~`PPU is compiled for another processor`~~
	167	+	```text
	168	+	[TExternalToolList.Run] CmdLine="/usr/bin/ppc386 -S2cgi -OG1 -Ppowerpc -gl -vewnhi -l -Fu../../lcl/units/powerpc-linux/ -Fu../../lcl/units/powerpc-linux/gtk2/ -Fu../../packager/units/powerpc-linux/ -Fu. -FU/home/sam/.lazarus/lib/JPEGForLazarus/powerpc-linux/ -dLCL -dLCLgtk2 jpegforlazarus.pas"
	169	+	...
	170	+	Target OS: Linux for i386
	171	+	...
	172	+	PPU Loading /usr/share/lazarus/lcl/units/powerpc-linux/intfgraphics.ppu
	173	+	PPU is compiled for another processor
	174	+	```
169	175
170	176		Which suggest in this case that ppc386 is set in the Environment menu instead of fpc
171	177
172	178		### Case 3.4: make , apt or fpcUPdeluxe installed a 2nd compiler fpc into \$PATH
173	179
174	180		see [[install on Linux cheatsheet]] how to move the 2nd fpc out of the \$PATH . Click "project options / Test" for diagnosis of this condition.
175	181
176	182		---
177	183		From the Free Pascal wiki, page "Unit not found - How to find units", as it stood on 2020-11-01 after a change by Unxed, 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).
178	184		Category: FPC
179	185		Category: Lazarus
180	186		Category: Troubleshooting

Back to history