diff options
| -rw-r--r-- | lib/core/macros.nim | 26 | ||||
| -rw-r--r-- | lib/pure/os.nim | 7 | ||||
| -rw-r--r-- | lib/system.nim | 14 |
3 files changed, 42 insertions, 5 deletions
diff --git a/lib/core/macros.nim b/lib/core/macros.nim index 16e859092..818b62a40 100644 --- a/lib/core/macros.nim +++ b/lib/core/macros.nim @@ -1626,9 +1626,29 @@ macro unpackVarargs*(callee: untyped; args: varargs[untyped]): untyped = result.add args[i] proc getProjectPath*(): string = discard - ## Returns the path to the currently compiling project, not to - ## be confused with ``system.currentSourcePath`` which returns - ## the path of the current module. + ## Returns the path to the currently compiling project. + ## + ## This is not to be confused with `system.currentSourcePath <system.html#currentSourcePath.t>`_ + ## which returns the path of the source file containing that template + ## call. + ## + ## For example, assume a ``dir1/foo.nim`` that imports a ``dir2/bar.nim``, + ## have the ``bar.nim`` print out both ``getProjectPath`` and + ## ``currentSourcePath`` outputs. + ## + ## Now when ``foo.nim`` is compiled, the ``getProjectPath`` from + ## ``bar.nim`` will return the ``dir1/`` path, while the ``currentSourcePath`` + ## will return the path to the ``bar.nim`` source file. + ## + ## Now when ``bar.nim`` is compiled directly, the ``getProjectPath`` + ## will now return the ``dir2/`` path, and the ``currentSourcePath`` + ## will still return the same path, the path to the ``bar.nim`` source + ## file. + ## + ## The path returned by this proc is set at compile time. + ## + ## See also: + ## * `getCurrentDir proc <os.html#getCurrentDir>`_ when defined(nimMacrosSizealignof): proc getSize*(arg: NimNode): int {.magic: "NSizeOf", noSideEffect.} = diff --git a/lib/pure/os.nim b/lib/pure/os.nim index a43a9cb32..c5d66f1ee 100644 --- a/lib/pure/os.nim +++ b/lib/pure/os.nim @@ -1236,13 +1236,18 @@ proc fileNewer*(a, b: string): bool {.rtl, extern: "nos$1", noNimScript.} = result = getLastModificationTime(a) > getLastModificationTime(b) proc getCurrentDir*(): string {.rtl, extern: "nos$1", tags: [], noNimScript.} = - ## Returns the `current working directory`:idx:. + ## Returns the `current working directory`:idx: i.e. where the built + ## binary is run. + ## + ## So the path returned by this proc is determined at run time. ## ## See also: ## * `getHomeDir proc <#getHomeDir>`_ ## * `getConfigDir proc <#getConfigDir>`_ ## * `getTempDir proc <#getTempDir>`_ ## * `setCurrentDir proc <#setCurrentDir,string>`_ + ## * `currentSourcePath template <system.html#currentSourcePath.t>`_ + ## * `getProjectPath proc <macros.html#getProjectPath>`_ when defined(windows): var bufsize = MAX_PATH.int32 when useWinUnicode: diff --git a/lib/system.nim b/lib/system.nim index d8c70179a..20687e4f1 100644 --- a/lib/system.nim +++ b/lib/system.nim @@ -4183,7 +4183,19 @@ when declared(File): template `&=`*(f: File, x: typed) = write(f, x) template currentSourcePath*: string = instantiationInfo(-1, true).filename - ## returns the full file-system path of the current source + ## Returns the full file-system path of the current source. + ## + ## To get the directory containing the current source, use it with + ## `os.parentDir() <os.html#parentDir%2Cstring>`_ as ``currentSourcePath.parentDir()``. + ## + ## The path returned by this template is set at compile time. + ## + ## See the docstring of `macros.getProjectPath() <macros.html#getProjectPath>`_ + ## for an example to see the distinction between the ``currentSourcePath`` + ## and ``getProjectPath``. + ## + ## See also: + ## * `getCurrentDir proc <os.html#getCurrentDir>`_ when compileOption("rangechecks"): template rangeCheck*(cond) = |