Update doc string for `@trace_compile`

[charleskawczynski]

It seems like @trace_compile just doesn't work on my machine. I'm happy to post whatever other information people may find useful to debug.

1.12-nightly

Charlies-iMac-2:ClimaAtmos.jl charliekawczynski$ julia +1.12-nightly
               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.12.0-DEV.2122 (2025-03-24)
 _/ |\__'_|_|_|\__'_|  |  release-1.12/aee98f8d005 (fork: 146 commits, 50 days)
|__/                   |

help?> @trace_compile
  @trace_compile

  A macro to execute an expression and show any methods that were compiled (or
  recompiled in yellow), like the julia args --trace-compile=stderr
  --trace-compile-timing but specifically for a call.

  julia> @trace_compile rand(2,2) * rand(2,2)
  #=   39.1 ms =# precompile(Tuple{typeof(Base.rand), Int64, Int64})
  #=  102.0 ms =# precompile(Tuple{typeof(Base.:(*)), Array{Float64, 2}, Array{Float64, 2}})
  2×2 Matrix{Float64}:
   0.421704  0.864841
   0.211262  0.444366

  │ Julia 1.12
  │
  │  This macro requires at least Julia 1.12

julia> @trace_compile rand(2,2) * rand(2,2)
2×2 Matrix{Float64}:
 0.963859  1.19601
 0.409505  0.728401

julia> versioninfo()
Julia Version 1.12.0-DEV.2122
Commit aee98f8d005 (2025-03-24 07:38 UTC)
Build Info:
  Official https://julialang.org release
Platform Info:
  OS: macOS (arm64-apple-darwin24.0.0)
  CPU: 8 × Apple M1
  WORD_SIZE: 64
  LLVM: libLLVM-18.1.7 (ORCJIT, apple-m1)
  GC: Built with stock GC
Threads: 1 default, 1 interactive, 1 GC (on 4 virtual cores)

1.13-nightly

Charlies-iMac-2:ClimaAtmos.jl charliekawczynski$ julia +nightly
               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.13.0-DEV.303 (2025-03-26)
 _/ |\__'_|_|_|\__'_|  |  Commit 01798fa6ebf (0 days old master)
|__/                   |

help?> @trace_compile
  @trace_compile

  A macro to execute an expression and show any methods that were compiled (or
  recompiled in yellow), like the julia args --trace-compile=stderr
  --trace-compile-timing but specifically for a call.

  julia> @trace_compile rand(2,2) * rand(2,2)
  #=   39.1 ms =# precompile(Tuple{typeof(Base.rand), Int64, Int64})
  #=  102.0 ms =# precompile(Tuple{typeof(Base.:(*)), Array{Float64, 2}, Array{Float64, 2}})
  2×2 Matrix{Float64}:
   0.421704  0.864841
   0.211262  0.444366

  │ Julia 1.12
  │
  │  This macro requires at least Julia 1.12

julia> @trace_compile rand(2,2) * rand(2,2)
2×2 Matrix{Float64}:
 0.462195  1.14774
 0.267721  0.90006
julia> versioninfo()
Julia Version 1.13.0-DEV.303
Commit 01798fa6ebf (2025-03-26 08:40 UTC)
Build Info:
  Official https://julialang.org release
Platform Info:
  OS: macOS (arm64-apple-darwin24.0.0)
  CPU: 8 × Apple M1
  WORD_SIZE: 64
  LLVM: libLLVM-19.1.7 (ORCJIT, apple-m1)
  GC: Built with stock GC
Threads: 1 default, 1 interactive, 1 GC (on 4 virtual cores)

[KristofferC]

I think you need to use the @eval trick like you need to use for @time to get accurate compilation time:

julia> @trace_compile @eval rand(2,2) * rand(2,2);
#=    9.0 ms =# precompile(Tuple{Core.GeneratedFunctionStub, UInt64, Method, Any, Vararg{Any}}) # recompile
#=   28.6 ms =# precompile(Tuple{typeof(Base.rand), Int64, Int64})
#=    2.6 ms =# precompile(Tuple{typeof(Base.:(*)), Array{Float64, 2}, Array{Float64, 2}})

Docstring should probably be updated.

[charleskawczynski]

That does work for me, thanks!

[charleskawczynski]

I'll update the title

[charleskawczynski]

What's odd though is that I think @Sbozzolo did not observe this on his machine