options

Source Edit

Imports

lineinfos, platform, prefixmatches, pathutils, nimpaths

Types

Cfile = object
  nimname*: string
  cname*, obj*: AbsoluteFile
  flags*: set[CfileFlag]
  customArgs*: string

Source Edit

CfileFlag {.pure.} = enum
  Cached,                   ## no need to recompile this time
  External                   ## file was introduced via .compile pragma

Source Edit

CfileList = seq[Cfile]

Source Edit

Command = enum
  cmdNone, cmdUnknown, cmdCompileToC, cmdCompileToCpp, cmdCompileToOC,
  cmdCompileToJS, cmdCrun, cmdTcc, cmdCheck, cmdM, cmdParse, cmdRod,
  cmdIdeTools, cmdNimscript, cmdDoc0, cmdDoc, cmdDoc2tex, cmdRst2html,
  cmdRst2tex, cmdMd2html, cmdMd2tex, cmdJsondoc0, cmdJsondoc, cmdCtags,
  cmdBuildindex, cmdGendepend, cmdDump, cmdInteractive, cmdNop, cmdJsonscript

Nim's commands Source Edit

ConfigRef {.acyclic.} = ref object
  backend*: TBackend
  target*: Target
  linesCompiled*: int
  options*: TOptions
  globalOptions*: TGlobalOptions
  macrosToExpand*: StringTableRef
  arcToExpand*: StringTableRef
  m*: MsgConfig
  filenameOption*: FilenameOption
  unitSep*: string
  evalTemplateCounter*: int
  evalMacroCounter*: int
  exitcode*: int8
  cmd*: Command
  cmdInput*: string
  projectIsCmd*: bool
  implicitCmd*: bool
  selectedGC*: TGCMode
  exc*: ExceptionSystem
  hintProcessingDots*: bool
  verbosity*: int
  numberOfProcessors*: int
  lastCmdTime*: float
  symbolFiles*: SymbolFilesOption
  spellSuggestMax*: int
  cppDefines*: HashSet[string]
  headerFile*: string
  nimbasePattern*: string
  features*: set[Feature]
  legacyFeatures*: set[LegacyFeature]
  arguments*: string         ## the arguments to be passed to the program that
                             ## should be run
  ideCmd*: IdeCmd
  cCompiler*: TSystemCC
  modifiedyNotes*: TNoteKinds
  cmdlineNotes*: TNoteKinds
  foreignPackageNotes*: TNoteKinds
  notes*: TNoteKinds
  warningAsErrors*: TNoteKinds
  mainPackageNotes*: TNoteKinds
  mainPackageId*: int
  errorCounter*: int
  hintCounter*: int
  warnCounter*: int
  errorMax*: int
  maxLoopIterationsVM*: int  ## VM: max iterations of all loops
  isVmTrace*: bool
  configVars*: StringTableRef
  symbols*: StringTableRef   ## We need to use a StringTableRef here as defined
                             ## symbols are always guaranteed to be style
                             ## insensitive. Otherwise hell would break lose.
  packageCache*: StringTableRef
  nimblePaths*: seq[AbsoluteDir]
  searchPaths*: seq[AbsoluteDir]
  lazyPaths*: seq[AbsoluteDir]
  outFile*: RelativeFile
  outDir*: AbsoluteDir
  jsonBuildFile*: AbsoluteFile
  prefixDir*, libpath*, nimcacheDir*: AbsoluteDir
  dllOverrides*, moduleOverrides*, cfileSpecificOptions*: StringTableRef
  projectName*: string
  projectPath*: AbsoluteDir
  projectFull*: AbsoluteFile
  projectIsStdin*: bool
  lastMsgWasDot*: set[StdOrrKind]
  projectMainIdx*: FileIndex
  projectMainIdx2*: FileIndex
  command*: string
  commandArgs*: seq[string]
  commandLine*: string
  extraCmds*: seq[string]
  implicitImports*: seq[string]
  implicitIncludes*: seq[string]
  docSeeSrcUrl*: string
  docRoot*: string           ## see nim --fullhelp for --docRoot
  docCmd*: string            ## see nim --fullhelp for --docCmd
  configFiles*: seq[AbsoluteFile]
  cIncludes*: seq[AbsoluteDir]
  cLibs*: seq[AbsoluteDir]
  cLinkedLibs*: seq[string]
  externalToLink*: seq[string]
  linkOptionsCmd*: string
  compileOptionsCmd*: seq[string]
  linkOptions*: string
  compileOptions*: string
  cCompilerPath*: string
  toCompile*: CfileList
  suggestionResultHook*: proc (result: Suggest) {.closure.}
  suggestVersion*: int
  suggestMaxResults*: int
  lastLineInfo*: TLineInfo
  writelnHook*: proc (output: string) {.closure, ...gcsafe.}
  structuredErrorHook*: proc (config: ConfigRef; info: TLineInfo; msg: string;
                              severity: Severity) {.closure, ...gcsafe.}
  cppCustomNamespace*: string
  nimMainPrefix*: string
  vmProfileData*: ProfileData
  expandProgress*: bool
  expandLevels*: int
  expandNodeResult*: string
  expandPosition*: TLineInfo
  currentConfigDir*: string
  clientProcessId*: int

every global configuration fields marked with '*' are subject to the incremental compilation mechanisms (+) means "part of the dependency" Source Edit

ExceptionSystem = enum
  excNone, excSetjmp, excCpp, excGoto, excQuirky

Source Edit

Feature = enum
  dotOperators, callOperator, parallel, destructor, notnil, dynamicBindSym,
  forLoopMacros, caseStmtMacros, codeReordering, compiletimeFFI, ## This requires building nim with `-d:nimHasLibFFI`
                                                                  ## which itself requires `koch installdeps libffi`, see #10150
                                                                  ## Note: this feature can't be localized with {.push.}
  vmopsDanger, strictFuncs, views, strictNotNil, overloadableEnums,
  strictEffects, unicodeOperators, flexibleOptionalParams, strictDefs,
  strictCaseObjects, inferGenericTypes, openSym, genericsOpenSym, vtables

experimental features; DO NOT RENAME THESE! Source Edit

FilenameOption = enum
  foAbs, foRelProject, foCanonical, foLegacyRelProj, foName, foStacktrace

Source Edit

IdeCmd = enum
  ideNone, ideSug, ideCon, ideDef, ideUse, ideDus, ideChk, ideChkFile, ideMod,
  ideHighlight, ideOutline, ideKnown, ideMsg, ideProject, ideGlobalSymbols,
  ideRecompile, ideChanged, ideType, ideDeclaration, ideExpand, ideInlayHints

Source Edit

LegacyFeature = enum
  allowSemcheckedAstModification, ## Allows to modify a NimNode where the type has already been
                                   ## flagged with nfSem. If you actually do this, it will cause
                                   ## bugs.
  checkUnsignedConversions, ## Historically and especially in version 1.0.0 of the language
                             ## conversions to unsigned numbers were checked. In 1.0.4 they
                             ## are not anymore.
  laxEffects,               ## Lax effects system prior to Nim 2.0.
  verboseTypeMismatch, emitGenerics, ## generics are emitted in the module that contains them.
                                      ## Useful for libraries that rely on local passC
  jsNoLambdaLifting          ## Old transformation for closures in JS backend

Source Edit

ProfileData = ref object
  data*: TableRef[TLineInfo, ProfileInfo]

Source Edit

ProfileInfo = object
  time*: float
  count*: int

Source Edit

StdOrrKind = enum
  stdOrrStdout, stdOrrStderr

Source Edit

Suggest = ref object
  section*: IdeCmd
  qualifiedPath*: seq[string]
  name*: ptr string
  filePath*: string
  line*: int
  column*: int
  doc*: string
  forth*: string
  quality*: range[0 .. 100] = 0
  isGlobal*: bool
  contextFits*: bool
  prefix*: PrefixMatch
  symkind*: byte
  scope*, localUsages*, globalUsages*: int
  tokenLen*: int
  version*: int
  endLine*: uint16
  endCol*: int
  inlayHintInfo*: SuggestInlayHint

Source Edit

SuggestInlayHint = ref object
  kind*: SuggestInlayHintKind
  line*: int
  column*: int
  label*: string
  paddingLeft*: bool
  paddingRight*: bool
  allowInsert*: bool
  tooltip*: string

Source Edit

SuggestInlayHintKind = enum
  sihkType = "Type", sihkParameter = "Parameter", sihkException = "Exception"

Source Edit

Suggestions = seq[Suggest]

Source Edit

SymbolFilesOption = enum
  disabledSf, writeOnlySf, readOnlySf, v2Sf, stressTest

Source Edit

TBackend = enum
  backendInvalid = "", backendC = "c", backendCpp = "cpp", backendJs = "js",
  backendObjc = "objc"

Source Edit

TGCMode = enum
  gcUnselected = "unselected", gcNone = "none", gcBoehm = "boehm",
  gcRegions = "regions", gcArc = "arc", gcOrc = "orc",
  gcAtomicArc = "atomicArc", gcMarkAndSweep = "markAndSweep", gcHooks = "hooks",
  gcRefc = "refc", gcGo = "go"

Source Edit

TGlobalOption = enum
  gloptNone, optForceFullMake, optWasNimscript, optListCmd, optCompileOnly,
  optNoLinking, optCDebug, optGenDynLib, optGenStaticLib, optGenGuiApp,
  optGenScript, optGenCDeps, optGenMapping, optRun, optUseNimcache,
  optStyleHint, optStyleError, optStyleUsages, optSkipSystemConfigFile,
  optSkipProjConfigFile, optSkipUserConfigFile, optSkipParentConfigFiles,
  optNoMain, optUseColors, optThreads, optStdout, optThreadAnalysis,
  optTlsEmulation, optGenIndex, optGenIndexOnly, optNoImportdoc,
  optEmbedOrigSrc, optIdeDebug, optIdeTerse, optIdeExceptionInlayHints,
  optExcessiveStackTrace, optShowAllMismatches, optWholeProject, optDocInternal,
  optMixedMode, optDeclaredLocs, optNoNimblePath, optHotCodeReloading,
  optDynlibOverrideAll, optSeqDestructors, optTinyRtti, optOwnedRefs,
  optMultiMethods, optBenchmarkVM, optProduceAsm, optPanics, optSourcemap,
  optProfileVM, optEnableDeepCopy, optShowNonExportedFields, optJsBigInt64

Source Edit

TGlobalOptions = set[TGlobalOption]

Source Edit

TOption = enum
  optNone, optObjCheck, optFieldCheck, optRangeCheck, optBoundsCheck,
  optOverflowCheck, optRefCheck, optNaNCheck, optInfCheck, optStaticBoundsCheck,
  optStyleCheck, optAssert, optLineDir, optWarns, optHints, optOptimizeSpeed,
  optOptimizeSize, optStackTrace, optStackTraceMsgs, optLineTrace, optByRef,
  optProfiler, optImplicitStatic, optTrMacros, optMemTracker, optSinkInference,
  optCursorInference, optImportHidden, optQuirky

Source Edit

TOptions = set[TOption]

Source Edit

TStringSeq = seq[string]

Source Edit

TSystemCC = enum
  ccNone, ccGcc, ccNintendoSwitch, ccLLVM_Gcc, ccCLang, ccBcc, ccVcc, ccTcc,
  ccEnv, ccIcl, ccIcc, ccClangCl, ccHipcc, ccNvcc

Source Edit

Consts

ChecksOptions = {optObjCheck, optFieldCheck, optRangeCheck, optOverflowCheck,
                 optBoundsCheck, optAssert, optNaNCheck, optInfCheck,
                 optStyleCheck}

Source Edit

cmdBackends = {cmdCompileToC, cmdCompileToCpp, cmdCompileToOC, cmdCompileToJS,
               cmdCrun}

Source Edit

cmdDocLike = {cmdDoc0, cmdDoc, cmdDoc2tex, cmdJsondoc0, cmdJsondoc, cmdCtags,
              cmdBuildindex}

Source Edit

copyrightYear = "2024"

Source Edit

DefaultConfig = r"nim.cfg"

Source Edit

DefaultConfigNims = r"config.nims"

Source Edit

DefaultGlobalOptions = {optThreadAnalysis, optExcessiveStackTrace, optJsBigInt64}

Source Edit

DefaultOptions = {optObjCheck, optFieldCheck, optRangeCheck, optBoundsCheck,
                  optOverflowCheck, optAssert, optWarns, optRefCheck, optHints,
                  optStackTrace, optLineTrace, optTrMacros, optStyleCheck,
                  optCursorInference}

Source Edit

DocConfig = r"nimdoc.cfg"

Source Edit

docRootDefault = "@default"

Source Edit

DocTexConfig = r"nimdoc.tex.cfg"

Source Edit

foreignPackageNotesDefault = {hintProcessing, warnUnknownMagic, hintQuitCalled,
                              hintExecuting, hintUser, warnUser}

Source Edit

genSubDir = r"nimcache"

Source Edit

harmlessOptions = {optForceFullMake, optNoLinking, optRun, optUseColors,
                   optStdout}

Source Edit

hasFFI = false

Source Edit

hasTinyCBackend = false

Source Edit

htmldocsDir = "htmldocs"

Source Edit

HtmlExt = "html"

Source Edit

IniExt = "ini"

Source Edit

JsonExt = "json"

Source Edit

nimEnableCovariance = false

Source Edit

NimExt = "nim"

Source Edit

oKeepVariableNames = true

Source Edit

oldExperimentalFeatures = {dotOperators, callOperator, parallel}

Source Edit

RodExt = "rod"

Source Edit

spellSuggestSecretSauce = -1

Source Edit

stdlibDirs = ["pure", "core", "arch", "pure/collections", "pure/concurrency",
              "pure/unidecode", "impure", "wrappers", "wrappers/linenoise",
              "windows", "posix", "js", "deprecated/pure"]

Source Edit

stdPrefix = "std/"

Source Edit

TagsExt = "tags"

Source Edit

TexExt = "tex"

Source Edit

useEffectSystem = true

Source Edit

useWriteTracking = false

Source Edit

Procs

proc `$`(c: IdeCmd): string {....raises: [], tags: [], forbids: [].}

Source Edit

proc absOutFile(conf: ConfigRef): AbsoluteFile {....raises: [OSError], tags: [],
    forbids: [].}

Source Edit

proc assignIfDefault[T](result: var T; val: T; def = default(T))

if result was already assigned to a value (that wasn't def), this is a noop. Source Edit

proc canonicalImport(conf: ConfigRef; file: AbsoluteFile): string {.
    ...raises: [Exception, KeyError, OSError], tags: [RootEffect, ReadDirEffect],
    forbids: [].}

Source Edit

proc canonicalImportAux(conf: ConfigRef; file: AbsoluteFile): string {.
    ...raises: [Exception, KeyError, OSError], tags: [RootEffect, ReadDirEffect],
    forbids: [].}

Shows the canonical module import, e.g.: system, std/tables, fusion/pointers, system/assertions, std/private/asciitables Source Edit

proc canonicalizePath(conf: ConfigRef; path: AbsoluteFile): AbsoluteFile {.
    ...raises: [OSError], tags: [ReadDirEffect], forbids: [].}

Source Edit

proc clearNimblePath(conf: ConfigRef) {....raises: [], tags: [], forbids: [].}

Source Edit

proc completeGeneratedFilePath(conf: ConfigRef; f: AbsoluteFile;
                               createSubDir: bool = true): AbsoluteFile {.
    ...raises: [OSError, IOError],
    tags: [ReadEnvEffect, ReadIOEffect, WriteDirEffect, ReadDirEffect],
    forbids: [].}

Return an absolute path of a generated intermediary file. Optionally creates the cache directory if createSubDir is true. Source Edit

proc cppDefine(c: ConfigRef; define: string) {....raises: [], tags: [], forbids: [].}

Source Edit

proc disableNimblePath(conf: ConfigRef) {....raises: [], tags: [], forbids: [].}

Source Edit

proc existsConfigVar(conf: ConfigRef; key: string): bool {....raises: [], tags: [],
    forbids: [].}

Source Edit

proc expandDone(conf: ConfigRef): bool {....raises: [], tags: [], forbids: [].}

Source Edit

proc findFile(conf: ConfigRef; f: string; suppressStdlib = false): AbsoluteFile {.
    ...raises: [OSError, KeyError], tags: [ReadDirEffect], forbids: [].}

Source Edit

proc findModule(conf: ConfigRef; modulename, currentModule: string): AbsoluteFile {.
    ...raises: [OSError, KeyError], tags: [ReadDirEffect], forbids: [].}

Source Edit

proc findProjectNimFile(conf: ConfigRef; pkg: string): string {.
    ...raises: [OSError], tags: [ReadDirEffect], forbids: [].}

Source Edit

proc floatInt64Align(conf: ConfigRef): int16 {....raises: [], tags: [], forbids: [].}

Returns either 4 or 8 depending on reasons. Source Edit

proc getClockStr(): string {....raises: [], tags: [ReadEnvEffect, TimeEffect],
                             forbids: [].}

Source Edit

proc getConfigVar(conf: ConfigRef; key: string; default = ""): string {.
    ...raises: [], tags: [], forbids: [].}

Source Edit

proc getDateStr(): string {....raises: [], tags: [ReadEnvEffect, TimeEffect],
                            forbids: [].}

Source Edit

proc getNimbleFile(conf: ConfigRef; path: string): string {.
    ...raises: [KeyError, OSError], tags: [ReadDirEffect], forbids: [].}

returns absolute path to nimble file, e.g.: /pathto/cligen.nimble Source Edit

proc getNimcacheDir(conf: ConfigRef): AbsoluteDir {....raises: [OSError],
    tags: [ReadEnvEffect, ReadIOEffect], forbids: [].}

Source Edit

proc getOutFile(conf: ConfigRef; filename: RelativeFile; ext: string): AbsoluteFile {.
    ...raises: [OSError], tags: [], forbids: [].}

Source Edit

proc getPackageName(conf: ConfigRef; path: string): string {.
    ...raises: [KeyError, OSError], tags: [ReadDirEffect], forbids: [].}

returns nimble package name, e.g.: cligen Source Edit

proc getPrefixDir(conf: ConfigRef): AbsoluteDir {....raises: [],
    tags: [ReadIOEffect], forbids: [].}

Gets the prefix dir, usually the parent directory where the binary resides.

This is overridden by some tools (namely nimsuggest) via the conf.prefixDir field. This should resolve to root of nim sources, whether running nim from a local clone or using installed nim, so that these exist: result/doc/advopt.txt and result/lib/system.nim

Source Edit

proc getRelativePathFromConfigPath(conf: ConfigRef; f: AbsoluteFile;
                                   isTitle = false): RelativeFile {.
    ...raises: [Exception], tags: [RootEffect], forbids: [].}

Source Edit

proc hasHint(conf: ConfigRef; note: TNoteKind): bool {....raises: [], tags: [],
    forbids: [].}

Source Edit

proc hasWarn(conf: ConfigRef; note: TNoteKind): bool {.inline, ...raises: [],
    tags: [], forbids: [].}

Source Edit

proc hcrOn(conf: ConfigRef): bool {....raises: [], tags: [], forbids: [].}

Source Edit

proc importantComments(conf: ConfigRef): bool {.inline, ...raises: [], tags: [],
    forbids: [].}

Source Edit

proc inclDynlibOverride(conf: ConfigRef; lib: string) {....raises: [], tags: [],
    forbids: [].}

Source Edit

proc isDefined(conf: ConfigRef; symbol: string): bool {....raises: [], tags: [],
    forbids: [].}

Source Edit

proc isDynlibOverride(conf: ConfigRef; lib: string): bool {....raises: [],
    tags: [], forbids: [].}

Source Edit

proc mainCommandArg(conf: ConfigRef): string {....raises: [], tags: [], forbids: [].}

This is intended for commands like check or parse which will work on the main project file unless explicitly given a specific file argument Source Edit

proc newConfigRef(): ConfigRef {....raises: [], tags: [], forbids: [].}

Source Edit

proc newPartialConfigRef(): ConfigRef {....raises: [], tags: [], forbids: [].}

create a new ConfigRef that is only good enough for error reporting. Source Edit

proc parseIdeCmd(s: string): IdeCmd {....raises: [], tags: [], forbids: [].}

Source Edit

proc pathSubs(conf: ConfigRef; p, config: string): string {.
    ...raises: [ValueError, OSError], tags: [ReadEnvEffect, ReadIOEffect],
    forbids: [].}

Source Edit

proc prepareToWriteOutput(conf: ConfigRef): AbsoluteFile {.
    ...raises: [OSError, IOError], tags: [WriteDirEffect, ReadDirEffect],
    forbids: [].}

Create the output directory and returns a full path to the output file Source Edit

proc removeTrailingDirSep(path: string): string {....raises: [], tags: [],
    forbids: [].}

Source Edit

proc setConfigVar(conf: ConfigRef; key, val: string) {....raises: [], tags: [],
    forbids: [].}

Source Edit

proc setDefaultLibpath(conf: ConfigRef) {....raises: [OSError],
    tags: [ReadIOEffect, ReadDirEffect, ReadEnvEffect], forbids: [].}

Source Edit

proc setFromProjectName(conf: ConfigRef; projectName: string) {.
    ...raises: [OSError], tags: [ReadDirEffect], forbids: [].}

Source Edit

proc setNote(conf: ConfigRef; note: TNoteKind; enabled = true) {....raises: [],
    tags: [], forbids: [].}

Source Edit

proc setNoteDefaults(conf: ConfigRef; note: TNoteKind; enabled = true) {.
    ...raises: [], tags: [], forbids: [].}

Source Edit

proc showNonExportedFields(conf: ConfigRef) {....raises: [], tags: [], forbids: [].}

Source Edit

proc toGeneratedFile(conf: ConfigRef; path: AbsoluteFile; ext: string): AbsoluteFile {.
    ...raises: [OSError], tags: [ReadEnvEffect, ReadIOEffect], forbids: [].}

converts "/home/a/mymodule.nim", "rod" to "/home/a/nimcache/mymodule.rod" Source Edit

proc usesWriteBarrier(conf: ConfigRef): bool {.inline, ...raises: [], tags: [],
    forbids: [].}

Source Edit

Iterators

iterator nimbleSubs(conf: ConfigRef; p: string): string {....raises: [ValueError],
    tags: [], forbids: [].}

Source Edit

Templates

template compilationCachePresent(conf: ConfigRef): untyped

Source Edit

template newPackageCache(): untyped

Source Edit

template optPreserveOrigSource(conf: ConfigRef): untyped

Source Edit

template quitOrRaise(conf: ConfigRef; msg = "")

Source Edit

template setErrorMaxHighMaybe(conf: ConfigRef)

do not stop after first error (but honor --errorMax if provided) Source Edit