clang  3.7.0
MSVCToolChain.cpp
Go to the documentation of this file.
1 //===--- ToolChains.cpp - ToolChain Implementations -----------------------===//
2 //
3 // The LLVM Compiler Infrastructure
4 //
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
7 //
8 //===----------------------------------------------------------------------===//
9 
10 #include "ToolChains.h"
11 #include "Tools.h"
12 #include "clang/Basic/CharInfo.h"
13 #include "clang/Basic/Version.h"
15 #include "clang/Driver/Driver.h"
17 #include "clang/Driver/Options.h"
18 #include "llvm/ADT/StringExtras.h"
19 #include "llvm/Config/llvm-config.h"
20 #include "llvm/Option/Arg.h"
21 #include "llvm/Option/ArgList.h"
22 #include "llvm/Support/ErrorHandling.h"
23 #include "llvm/Support/FileSystem.h"
24 #include "llvm/Support/Process.h"
25 #include <cstdio>
26 
27 // Include the necessary headers to interface with the Windows registry and
28 // environment.
29 #if defined(LLVM_ON_WIN32)
30 #define USE_WIN32
31 #endif
32 
33 #ifdef USE_WIN32
34  #define WIN32_LEAN_AND_MEAN
35  #define NOGDI
36  #ifndef NOMINMAX
37  #define NOMINMAX
38  #endif
39  #include <windows.h>
40 #endif
41 
42 using namespace clang::driver;
43 using namespace clang::driver::toolchains;
44 using namespace clang;
45 using namespace llvm::opt;
46 
47 MSVCToolChain::MSVCToolChain(const Driver &D, const llvm::Triple& Triple,
48  const ArgList &Args)
49  : ToolChain(D, Triple, Args) {
50  getProgramPaths().push_back(getDriver().getInstalledDir());
51  if (getDriver().getInstalledDir() != getDriver().Dir)
52  getProgramPaths().push_back(getDriver().Dir);
53 }
54 
56  return new tools::visualstudio::Linker(*this);
57 }
58 
60  if (getTriple().isOSBinFormatMachO())
61  return new tools::darwin::Assembler(*this);
62  getDriver().Diag(clang::diag::err_no_external_assembler);
63  return nullptr;
64 }
65 
67  return true;
68 }
69 
71  // Emit unwind tables by default on Win64. All non-x86_32 Windows platforms
72  // such as ARM and PPC actually require unwind tables, but LLVM doesn't know
73  // how to generate them yet.
74  return getArch() == llvm::Triple::x86_64;
75 }
76 
78  return getArch() == llvm::Triple::x86_64;
79 }
80 
82  return false;
83 }
84 
86  return getArch() == llvm::Triple::x86_64;
87 }
88 
89 #ifdef USE_WIN32
90 static bool readFullStringValue(HKEY hkey, const char *valueName,
91  std::string &value) {
92  // FIXME: We should be using the W versions of the registry functions, but
93  // doing so requires UTF8 / UTF16 conversions similar to how we handle command
94  // line arguments. The UTF8 conversion functions are not exposed publicly
95  // from LLVM though, so in order to do this we will probably need to create
96  // a registry abstraction in LLVMSupport that is Windows only.
97  DWORD result = 0;
98  DWORD valueSize = 0;
99  DWORD type = 0;
100  // First just query for the required size.
101  result = RegQueryValueEx(hkey, valueName, NULL, &type, NULL, &valueSize);
102  if (result != ERROR_SUCCESS || type != REG_SZ)
103  return false;
104  std::vector<BYTE> buffer(valueSize);
105  result = RegQueryValueEx(hkey, valueName, NULL, NULL, &buffer[0], &valueSize);
106  if (result == ERROR_SUCCESS)
107  value.assign(reinterpret_cast<const char *>(buffer.data()));
108  return result;
109 }
110 #endif
111 
112 /// \brief Read registry string.
113 /// This also supports a means to look for high-versioned keys by use
114 /// of a $VERSION placeholder in the key path.
115 /// $VERSION in the key path is a placeholder for the version number,
116 /// causing the highest value path to be searched for and used.
117 /// I.e. "SOFTWARE\\Microsoft\\VisualStudio\\$VERSION".
118 /// There can be additional characters in the component. Only the numeric
119 /// characters are compared. This function only searches HKLM.
120 static bool getSystemRegistryString(const char *keyPath, const char *valueName,
121  std::string &value, std::string *phValue) {
122 #ifndef USE_WIN32
123  return false;
124 #else
125  HKEY hRootKey = HKEY_LOCAL_MACHINE;
126  HKEY hKey = NULL;
127  long lResult;
128  bool returnValue = false;
129 
130  const char *placeHolder = strstr(keyPath, "$VERSION");
131  std::string bestName;
132  // If we have a $VERSION placeholder, do the highest-version search.
133  if (placeHolder) {
134  const char *keyEnd = placeHolder - 1;
135  const char *nextKey = placeHolder;
136  // Find end of previous key.
137  while ((keyEnd > keyPath) && (*keyEnd != '\\'))
138  keyEnd--;
139  // Find end of key containing $VERSION.
140  while (*nextKey && (*nextKey != '\\'))
141  nextKey++;
142  size_t partialKeyLength = keyEnd - keyPath;
143  char partialKey[256];
144  if (partialKeyLength > sizeof(partialKey))
145  partialKeyLength = sizeof(partialKey);
146  strncpy(partialKey, keyPath, partialKeyLength);
147  partialKey[partialKeyLength] = '\0';
148  HKEY hTopKey = NULL;
149  lResult = RegOpenKeyEx(hRootKey, partialKey, 0, KEY_READ | KEY_WOW64_32KEY,
150  &hTopKey);
151  if (lResult == ERROR_SUCCESS) {
152  char keyName[256];
153  double bestValue = 0.0;
154  DWORD index, size = sizeof(keyName) - 1;
155  for (index = 0; RegEnumKeyEx(hTopKey, index, keyName, &size, NULL,
156  NULL, NULL, NULL) == ERROR_SUCCESS; index++) {
157  const char *sp = keyName;
158  while (*sp && !isDigit(*sp))
159  sp++;
160  if (!*sp)
161  continue;
162  const char *ep = sp + 1;
163  while (*ep && (isDigit(*ep) || (*ep == '.')))
164  ep++;
165  char numBuf[32];
166  strncpy(numBuf, sp, sizeof(numBuf) - 1);
167  numBuf[sizeof(numBuf) - 1] = '\0';
168  double dvalue = strtod(numBuf, NULL);
169  if (dvalue > bestValue) {
170  // Test that InstallDir is indeed there before keeping this index.
171  // Open the chosen key path remainder.
172  bestName = keyName;
173  // Append rest of key.
174  bestName.append(nextKey);
175  lResult = RegOpenKeyEx(hTopKey, bestName.c_str(), 0,
176  KEY_READ | KEY_WOW64_32KEY, &hKey);
177  if (lResult == ERROR_SUCCESS) {
178  lResult = readFullStringValue(hKey, valueName, value);
179  if (lResult == ERROR_SUCCESS) {
180  bestValue = dvalue;
181  if (phValue)
182  *phValue = bestName;
183  returnValue = true;
184  }
185  RegCloseKey(hKey);
186  }
187  }
188  size = sizeof(keyName) - 1;
189  }
190  RegCloseKey(hTopKey);
191  }
192  } else {
193  lResult =
194  RegOpenKeyEx(hRootKey, keyPath, 0, KEY_READ | KEY_WOW64_32KEY, &hKey);
195  if (lResult == ERROR_SUCCESS) {
196  lResult = readFullStringValue(hKey, valueName, value);
197  if (lResult == ERROR_SUCCESS)
198  returnValue = true;
199  if (phValue)
200  phValue->clear();
201  RegCloseKey(hKey);
202  }
203  }
204  return returnValue;
205 #endif // USE_WIN32
206 }
207 
208 /// \brief Get Windows SDK installation directory.
209 bool MSVCToolChain::getWindowsSDKDir(std::string &path, int &major,
210  int &minor) const {
211  std::string sdkVersion;
212  // Try the Windows registry.
213  bool hasSDKDir = getSystemRegistryString(
214  "SOFTWARE\\Microsoft\\Microsoft SDKs\\Windows\\$VERSION",
215  "InstallationFolder", path, &sdkVersion);
216  if (!sdkVersion.empty())
217  std::sscanf(sdkVersion.c_str(), "v%d.%d", &major, &minor);
218  return hasSDKDir && !path.empty();
219 }
220 
221 // Gets the library path required to link against the Windows SDK.
222 bool MSVCToolChain::getWindowsSDKLibraryPath(std::string &path) const {
223  std::string sdkPath;
224  int sdkMajor = 0;
225  int sdkMinor = 0;
226 
227  path.clear();
228  if (!getWindowsSDKDir(sdkPath, sdkMajor, sdkMinor))
229  return false;
230 
231  llvm::SmallString<128> libPath(sdkPath);
232  llvm::sys::path::append(libPath, "Lib");
233  if (sdkMajor <= 7) {
234  switch (getArch()) {
235  // In Windows SDK 7.x, x86 libraries are directly in the Lib folder.
236  case llvm::Triple::x86:
237  break;
238  case llvm::Triple::x86_64:
239  llvm::sys::path::append(libPath, "x64");
240  break;
241  case llvm::Triple::arm:
242  // It is not necessary to link against Windows SDK 7.x when targeting ARM.
243  return false;
244  default:
245  return false;
246  }
247  } else {
248  // Windows SDK 8.x installs libraries in a folder whose names depend on the
249  // version of the OS you're targeting. By default choose the newest, which
250  // usually corresponds to the version of the OS you've installed the SDK on.
251  const char *tests[] = {"winv6.3", "win8", "win7"};
252  bool found = false;
253  for (const char *test : tests) {
254  llvm::SmallString<128> testPath(libPath);
255  llvm::sys::path::append(testPath, test);
256  if (llvm::sys::fs::exists(testPath.c_str())) {
257  libPath = testPath;
258  found = true;
259  break;
260  }
261  }
262 
263  if (!found)
264  return false;
265 
266  llvm::sys::path::append(libPath, "um");
267  switch (getArch()) {
268  case llvm::Triple::x86:
269  llvm::sys::path::append(libPath, "x86");
270  break;
271  case llvm::Triple::x86_64:
272  llvm::sys::path::append(libPath, "x64");
273  break;
274  case llvm::Triple::arm:
275  llvm::sys::path::append(libPath, "arm");
276  break;
277  default:
278  return false;
279  }
280  }
281 
282  path = libPath.str();
283  return true;
284 }
285 
286 // Get the location to use for Visual Studio binaries. The location priority
287 // is: %VCINSTALLDIR% > %PATH% > newest copy of Visual Studio installed on
288 // system (as reported by the registry).
289 bool MSVCToolChain::getVisualStudioBinariesFolder(const char *clangProgramPath,
290  std::string &path) const {
291  path.clear();
292 
293  SmallString<128> BinDir;
294 
295  // First check the environment variables that vsvars32.bat sets.
296  llvm::Optional<std::string> VcInstallDir =
297  llvm::sys::Process::GetEnv("VCINSTALLDIR");
298  if (VcInstallDir.hasValue()) {
299  BinDir = VcInstallDir.getValue();
300  llvm::sys::path::append(BinDir, "bin");
301  } else {
302  // Next walk the PATH, trying to find a cl.exe in the path. If we find one,
303  // use that. However, make sure it's not clang's cl.exe.
304  llvm::Optional<std::string> OptPath = llvm::sys::Process::GetEnv("PATH");
305  if (OptPath.hasValue()) {
306  const char EnvPathSeparatorStr[] = {llvm::sys::EnvPathSeparator, '\0'};
307  SmallVector<StringRef, 8> PathSegments;
308  llvm::SplitString(OptPath.getValue(), PathSegments, EnvPathSeparatorStr);
309 
310  for (StringRef PathSegment : PathSegments) {
311  if (PathSegment.empty())
312  continue;
313 
314  SmallString<128> FilePath(PathSegment);
315  llvm::sys::path::append(FilePath, "cl.exe");
316  if (llvm::sys::fs::can_execute(FilePath.c_str()) &&
317  !llvm::sys::fs::equivalent(FilePath.c_str(), clangProgramPath)) {
318  // If we found it on the PATH, use it exactly as is with no
319  // modifications.
320  path = PathSegment;
321  return true;
322  }
323  }
324  }
325 
326  std::string installDir;
327  // With no VCINSTALLDIR and nothing on the PATH, if we can't find it in the
328  // registry then we have no choice but to fail.
329  if (!getVisualStudioInstallDir(installDir))
330  return false;
331 
332  // Regardless of what binary we're ultimately trying to find, we make sure
333  // that this is a Visual Studio directory by checking for cl.exe. We use
334  // cl.exe instead of other binaries like link.exe because programs such as
335  // GnuWin32 also have a utility called link.exe, so cl.exe is the least
336  // ambiguous.
337  BinDir = installDir;
338  llvm::sys::path::append(BinDir, "VC", "bin");
339  SmallString<128> ClPath(BinDir);
340  llvm::sys::path::append(ClPath, "cl.exe");
341 
342  if (!llvm::sys::fs::can_execute(ClPath.c_str()))
343  return false;
344  }
345 
346  if (BinDir.empty())
347  return false;
348 
349  switch (getArch()) {
350  case llvm::Triple::x86:
351  break;
352  case llvm::Triple::x86_64:
353  llvm::sys::path::append(BinDir, "amd64");
354  break;
355  case llvm::Triple::arm:
356  llvm::sys::path::append(BinDir, "arm");
357  break;
358  default:
359  // Whatever this is, Visual Studio doesn't have a toolchain for it.
360  return false;
361  }
362  path = BinDir.str();
363  return true;
364 }
365 
366 // Get Visual Studio installation directory.
367 bool MSVCToolChain::getVisualStudioInstallDir(std::string &path) const {
368  // First check the environment variables that vsvars32.bat sets.
369  const char *vcinstalldir = getenv("VCINSTALLDIR");
370  if (vcinstalldir) {
371  path = vcinstalldir;
372  path = path.substr(0, path.find("\\VC"));
373  return true;
374  }
375 
376  std::string vsIDEInstallDir;
377  std::string vsExpressIDEInstallDir;
378  // Then try the windows registry.
379  bool hasVCDir =
380  getSystemRegistryString("SOFTWARE\\Microsoft\\VisualStudio\\$VERSION",
381  "InstallDir", vsIDEInstallDir, nullptr);
382  if (hasVCDir && !vsIDEInstallDir.empty()) {
383  path = vsIDEInstallDir.substr(0, vsIDEInstallDir.find("\\Common7\\IDE"));
384  return true;
385  }
386 
387  bool hasVCExpressDir =
388  getSystemRegistryString("SOFTWARE\\Microsoft\\VCExpress\\$VERSION",
389  "InstallDir", vsExpressIDEInstallDir, nullptr);
390  if (hasVCExpressDir && !vsExpressIDEInstallDir.empty()) {
391  path = vsExpressIDEInstallDir.substr(
392  0, vsIDEInstallDir.find("\\Common7\\IDE"));
393  return true;
394  }
395 
396  // Try the environment.
397  const char *vs120comntools = getenv("VS120COMNTOOLS");
398  const char *vs100comntools = getenv("VS100COMNTOOLS");
399  const char *vs90comntools = getenv("VS90COMNTOOLS");
400  const char *vs80comntools = getenv("VS80COMNTOOLS");
401 
402  const char *vscomntools = nullptr;
403 
404  // Find any version we can
405  if (vs120comntools)
406  vscomntools = vs120comntools;
407  else if (vs100comntools)
408  vscomntools = vs100comntools;
409  else if (vs90comntools)
410  vscomntools = vs90comntools;
411  else if (vs80comntools)
412  vscomntools = vs80comntools;
413 
414  if (vscomntools && *vscomntools) {
415  const char *p = strstr(vscomntools, "\\Common7\\Tools");
416  path = p ? std::string(vscomntools, p) : vscomntools;
417  return true;
418  }
419  return false;
420 }
421 
422 void MSVCToolChain::AddSystemIncludeWithSubfolder(const ArgList &DriverArgs,
423  ArgStringList &CC1Args,
424  const std::string &folder,
425  const char *subfolder) const {
426  llvm::SmallString<128> path(folder);
427  llvm::sys::path::append(path, subfolder);
428  addSystemInclude(DriverArgs, CC1Args, path);
429 }
430 
431 void MSVCToolChain::AddClangSystemIncludeArgs(const ArgList &DriverArgs,
432  ArgStringList &CC1Args) const {
433  if (DriverArgs.hasArg(options::OPT_nostdinc))
434  return;
435 
436  if (!DriverArgs.hasArg(options::OPT_nobuiltininc)) {
437  SmallString<128> P(getDriver().ResourceDir);
438  llvm::sys::path::append(P, "include");
439  addSystemInclude(DriverArgs, CC1Args, P);
440  }
441 
442  if (DriverArgs.hasArg(options::OPT_nostdlibinc))
443  return;
444 
445  // Honor %INCLUDE%. It should know essential search paths with vcvarsall.bat.
446  if (const char *cl_include_dir = getenv("INCLUDE")) {
448  StringRef(cl_include_dir)
449  .split(Dirs, ";", /*MaxSplit=*/-1, /*KeepEmpty=*/false);
450  for (StringRef Dir : Dirs)
451  addSystemInclude(DriverArgs, CC1Args, Dir);
452  if (!Dirs.empty())
453  return;
454  }
455 
456  std::string VSDir;
457 
458  // When built with access to the proper Windows APIs, try to actually find
459  // the correct include paths first.
460  if (getVisualStudioInstallDir(VSDir)) {
461  AddSystemIncludeWithSubfolder(DriverArgs, CC1Args, VSDir, "VC\\include");
462 
463  std::string WindowsSDKDir;
464  int major, minor;
465  if (getWindowsSDKDir(WindowsSDKDir, major, minor)) {
466  if (major >= 8) {
467  AddSystemIncludeWithSubfolder(DriverArgs, CC1Args, WindowsSDKDir,
468  "include\\shared");
469  AddSystemIncludeWithSubfolder(DriverArgs, CC1Args, WindowsSDKDir,
470  "include\\um");
471  AddSystemIncludeWithSubfolder(DriverArgs, CC1Args, WindowsSDKDir,
472  "include\\winrt");
473  } else {
474  AddSystemIncludeWithSubfolder(DriverArgs, CC1Args, WindowsSDKDir,
475  "include");
476  }
477  } else {
478  addSystemInclude(DriverArgs, CC1Args, VSDir);
479  }
480  return;
481  }
482 
483  // As a fallback, select default install paths.
484  // FIXME: Don't guess drives and paths like this on Windows.
485  const StringRef Paths[] = {
486  "C:/Program Files/Microsoft Visual Studio 10.0/VC/include",
487  "C:/Program Files/Microsoft Visual Studio 9.0/VC/include",
488  "C:/Program Files/Microsoft Visual Studio 9.0/VC/PlatformSDK/Include",
489  "C:/Program Files/Microsoft Visual Studio 8/VC/include",
490  "C:/Program Files/Microsoft Visual Studio 8/VC/PlatformSDK/Include"
491  };
492  addSystemIncludes(DriverArgs, CC1Args, Paths);
493 }
494 
495 void MSVCToolChain::AddClangCXXStdlibIncludeArgs(const ArgList &DriverArgs,
496  ArgStringList &CC1Args) const {
497  // FIXME: There should probably be logic here to find libc++ on Windows.
498 }
499 
500 std::string
502  types::ID InputType) const {
503  std::string TripleStr =
505  llvm::Triple Triple(TripleStr);
506  VersionTuple MSVT =
507  tools::visualstudio::getMSVCVersion(/*D=*/nullptr, Triple, Args,
508  /*IsWindowsMSVC=*/true);
509  if (MSVT.empty())
510  return TripleStr;
511 
512  MSVT = VersionTuple(MSVT.getMajor(), MSVT.getMinor().getValueOr(0),
513  MSVT.getSubminor().getValueOr(0));
514 
515  if (Triple.getEnvironment() == llvm::Triple::MSVC) {
516  StringRef ObjFmt = Triple.getEnvironmentName().split('-').second;
517  if (ObjFmt.empty())
518  Triple.setEnvironmentName((Twine("msvc") + MSVT.getAsString()).str());
519  else
520  Triple.setEnvironmentName(
521  (Twine("msvc") + MSVT.getAsString() + Twine('-') + ObjFmt).str());
522  }
523  return Triple.getTriple();
524 }
525 
528  Res |= SanitizerKind::Address;
529  return Res;
530 }
const llvm::Triple & getTriple() const
Definition: ToolChain.h:123
static LLVM_READONLY bool isDigit(unsigned char c)
Return true if this character is an ASCII digit: [0-9].
Definition: CharInfo.h:94
bool IsIntegratedAssemblerDefault() const override
Represents a version number in the form major[.minor[.subminor[.build]]].
Definition: VersionTuple.h:26
Optional< unsigned > getMinor() const
Retrieve the minor version number, if provided.
Definition: VersionTuple.h:72
const Driver & getDriver() const
Definition: ToolChain.cpp:75
std::string ComputeEffectiveClangTriple(const llvm::opt::ArgList &Args, types::ID InputType) const override
bool isPIEDefault() const override
Test whether this toolchain defaults to PIE.
DiagnosticBuilder Diag(unsigned DiagID) const
Definition: Driver.h:72
llvm::Triple::ArchType getArch() const
Definition: ToolChain.h:125
virtual SanitizerMask getSupportedSanitizers() const
Return sanitizers which are available in this toolchain.
Definition: ToolChain.cpp:492
bool getVisualStudioInstallDir(std::string &path) const
void AddClangCXXStdlibIncludeArgs(const llvm::opt::ArgList &DriverArgs, llvm::opt::ArgStringList &CC1Args) const override
path_list & getProgramPaths()
Definition: ToolChain.h:141
std::string getAsString() const
Retrieve a string representation of the version number.
bool isPICDefault() const override
Test whether this toolchain defaults to PIC.
AnnotatingParser & P
static void addSystemIncludes(const llvm::opt::ArgList &DriverArgs, llvm::opt::ArgStringList &CC1Args, ArrayRef< StringRef > Paths)
Utility function to add a list of system include directories to CC1.
Definition: ToolChain.cpp:424
VersionTuple getMSVCVersion(const Driver *D, const llvm::Triple &Triple, const llvm::opt::ArgList &Args, bool IsWindowsMSVC)
Definition: Tools.cpp:2791
#define NULL
Definition: stddef.h:105
Defines version macros and version-related utility functions for Clang.
void AddClangSystemIncludeArgs(const llvm::opt::ArgList &DriverArgs, llvm::opt::ArgStringList &CC1Args) const override
Add the clang cc1 arguments for system include paths.
static bool getSystemRegistryString(const char *keyPath, const char *valueName, std::string &value, std::string *phValue)
Read registry string. This also supports a means to look for high-versioned keys by use of a $VERSION...
void AddSystemIncludeWithSubfolder(const llvm::opt::ArgList &DriverArgs, llvm::opt::ArgStringList &CC1Args, const std::string &folder, const char *subfolder) const
bool getWindowsSDKLibraryPath(std::string &path) const
unsigned getMajor() const
Retrieve the major version number.
Definition: VersionTuple.h:69
virtual std::string ComputeEffectiveClangTriple(const llvm::opt::ArgList &Args, types::ID InputType=types::TY_INVALID) const
Definition: ToolChain.cpp:347
static void addSystemInclude(const llvm::opt::ArgList &DriverArgs, llvm::opt::ArgStringList &CC1Args, const Twine &Path)
Utility function to add a system include directory to CC1 arguments.
Definition: ToolChain.cpp:394
bool getVisualStudioBinariesFolder(const char *clangProgramPath, std::string &path) const
uint64_t SanitizerMask
Definition: Sanitizers.h:24
const internal::VariadicAllOfMatcher< Type > type
Matches Types in the clang AST.
Definition: ASTMatchers.h:1639
bool empty() const
Determine whether this version information is empty (e.g., all version components are zero)...
Definition: VersionTuple.h:64
static __inline__ uint32_t volatile uint32_t * p
Definition: arm_acle.h:75
bool getWindowsSDKDir(std::string &path, int &major, int &minor) const
Get Windows SDK installation directory.
Tool - Information on a specific compilation tool.
Definition: Tool.h:34
Optional< unsigned > getSubminor() const
Retrieve the subminor version number, if provided.
Definition: VersionTuple.h:79
MSVCToolChain(const Driver &D, const llvm::Triple &Triple, const llvm::opt::ArgList &Args)
SanitizerMask getSupportedSanitizers() const override
Return sanitizers which are available in this toolchain.
ToolChain - Access to tools for a single platform.
Definition: ToolChain.h:43
bool isPICDefaultForced() const override
Tests whether this toolchain forces its default for PIC, PIE or non-PIC. If this returns true...