# compiler/options

Dark Mode

- Index

Search:
Group by:
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, cmdParse, cmdRod, cmdIdeTools,
      cmdNimscript, cmdDoc0, cmdDoc, cmdDoc2tex, cmdRst2html, cmdRst2tex,
      cmdJsondoc0, cmdJsondoc, cmdCtags, cmdBuildindex, cmdGendepend, cmdDump,
      cmdInteractive, cmdNop, cmdJsonscript, cmdNimfix

  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
      features*: set[Feature]
      legacyFeatures*: set[LegacyFeature]
      arguments*: string         ## the arguments to be passed to the program that
                                 ## should be run
      ideCmd*: IdeCmd
      oldNewlines*: bool
      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
      nimStdlibVersion*: NimVer
      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]
      keepComments*: bool
      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.}
      structuredErrorHook*: proc (config: ConfigRef; info: TLineInfo; msg: string;
                                  severity: Severity) {.closure, ...gcsafe.}
      cppCustomNamespace*: string
      nimMainPrefix*: string
      vmProfileData*: ProfileData

  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
      implicitDeref, dotOperators, callOperator, parallel, destructor, notnil,
      dynamicBindSym, forLoopMacros, caseStmtMacros, codeReordering, compiletimeFFI, ## This requires building nim with `-d:nimHasLibFFI`
                                                                                      ## which itself requires `nimble install libffi`, see #10150
                                                                                      ## Note: this feature can't be localized with {.push.}
      vmopsDanger, strictFuncs, views, strictNotNil, overloadableEnums,
      strictEffects, unicodeOperators, flexibleOptionalParams

  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

  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.

  Source Edit

    NimVer = tuple[major: int, minor: int, patch: int]

  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]
      isGlobal*: bool
      contextFits*: bool
      prefix*: PrefixMatch
      symkind*: byte
      scope*, localUsages*, globalUsages*: int
      tokenLen*: int
      version*: int

  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",
      gcMarkAndSweep = "markAndSweep", gcHooks = "hooks", gcRefc = "refc",
      gcV2 = "v2", gcGo = "go"

  Source Edit

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

  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

  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

  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 = "2021"

  Source Edit

    DefaultConfig = r"nim.cfg"

  Source Edit

    DefaultConfigNims = r"config.nims"

  Source Edit

    DefaultGlobalOptions = {optThreadAnalysis, optExcessiveStackTrace}

  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 = {implicitDeref, 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"]

  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: [].}

  Source Edit

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

  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].}

  Source Edit

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

  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].}

  Source Edit

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

  Source Edit

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

  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: [].}

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Returns either 4 or 8 depending on reasons. Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

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

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

  Source Edit

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

  Source Edit

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

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

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

  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].}

  Source Edit

    proc getStdlibVersion(conf: ConfigRef): NimVer {....raises: [ValueError], tags: [].}

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  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: [].}

  Source Edit

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

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

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

  Source Edit

    proc parseNimVersion(a: string): NimVer {....raises: [ValueError], tags: [].}

  Source Edit

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

  Source Edit

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

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

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

  Source Edit

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

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

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

  Source Edit

# Iterators

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

  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