Julia 사용하기

개요

Quarto는 마크다운 안에서 실행 가능한 Julia 코드 블록을 지원합니다. 이를 통해 완전한 재현 가능 문서와 보고서를 만들 수 있습니다. 출력에 필요한 Julia 코드는 문서 자체의 일부이며, 문서를 렌더링할 때마다 자동으로 다시 실행됩니다.

Quarto에는 Julia 코드를 실행하는 두 가지 엔진이 있습니다. 최신 julia 엔진은 QuartoNotebookRunner.jl 패키지로 노트북을 렌더링하고, 기존 jupyter 엔진은 IJulia Jupyter 커널을 사용합니다.

다음 표는 julia 엔진이 만들어진 이유 중 일부를 보여 줍니다.

	julia Engine	jupyter Engine
Julia 코드 블록 실행	✅	✅
빠른 재실행을 위한 세션 유지	✅	✅
Python 설치 불필요	✅	❌
전역 패키지 설치 불필요	✅	❌
juliaup 자동 통합(커널 설치 불필요)	✅	❌
Python & R 코드 블록(PythonCall.jl 및 RCall.jl 사용)	✅	❌
“확장 가능한 셀” 또는 프로그램적 문서 생성(QuartoTools.jl 사용)	✅	❌

Note

대부분의 사용자에게 julia 엔진이 가장 좋은 경험을 제공합니다. 하지만 하위 호환성을 위해 Julia 코드의 기본 엔진은 jupyter 엔진입니다. julia 엔진은 frontmatter 또는 프로젝트 파일에서 명시적으로 활성화해야 합니다.

두 엔진 중 어느 것을 사용하든 Julia를 수동으로 설치해야 합니다. juliaup으로 설치하는 것을 권장하며, 자세한 내용은 공식 Julia 웹사이트를 참고하세요.

이제 Julia 코드 블록을 포함한 문서를 만들고 렌더링하는 기본을 살펴봅니다.

코드 블록

언어 이름을 중괄호로 감싼 코드 블록(예: ```{julia})은 실행 가능하며, 렌더링 시 Quarto가 실행합니다. 아래는 간단한 예시입니다.

---
title: "Plots Demo"
author: "Norah Jones"
date: "5/22/2021"
format:
  html:
    code-fold: true
engine: julia
---

### Parametric Plots

Plot function pair (x(u), y(u)). 
See @fig-parametric for an example.

```{julia}
#| label: fig-parametric
#| fig-cap: "Parametric Plots"

using Plots

plot(sin, 
     x->sin(2x), 
     0, 
     2π, 
     leg=false, 
     fill=(0,:lavender))
```

코드 블록 상단에 있는 특수 주석은 그림을 상호 참조할 수 있도록 하는 셀 수준 옵션입니다.

이 문서는 다음과 같은 렌더링 결과를 생성합니다.

Plots Demo 출력 예시: 제목, 저자, 날짜가 표시되고 Parametric plots 섹션에 텍스트, 코드 접기 영역, 플롯 출력과 Figure 1 Parametric Plots 캡션이 있다.

실행 가능한 코드 블록으로 플롯, 데이터 프레임의 표 출력, 일반 텍스트 출력(예: 통계 요약 결과 출력) 등 다양한 유형의 출력을 생성할 수 있습니다.

코드 실행과 출력 동작을 제어하는 다양한 옵션이 있으며, 자세한 내용은 실행 옵션 문서에서 확인할 수 있습니다.

마크다운 흐름을 끊는 코드 블록 외에도 인라인 코드를 포함할 수 있습니다. 인라인 코드에 대한 자세한 내용은 인라인 코드 문서를 참고하세요.

다중 출력

기본적으로 Julia 셀은 마지막 표현식의 값을 자동으로 출력합니다(위 예시에서 plot() 호출 결과가 출력된 것과 동일). 하나의 셀에서 여러 플롯(또는 다른 출력)을 표시하려면 display() 함수를 명시적으로 호출해야 합니다. 예를 들어 아래는 두 개의 플롯을 하위 캡션과 함께 나란히 출력합니다.

```{julia}
#| label: fig-plots
#| fig-cap: "Multiple Plots"
#| fig-subcap:
#|   - "Plot 1"
#|   - "Plot 2"
#| layout-ncol: 2

using Plots
display(plot(sin, x -> sin(2x), 0, 2))
display(plot(x -> sin(4x), y -> sin(5y), 0, 2))
```

렌더링

Quarto는 실행 가능한 코드 블록이 포함된 모든 마크다운 문서에서 계산을 자동으로 실행합니다. 예를 들어 앞서 보인 예제는 다음과 같이 다양한 포맷으로 렌더링할 수 있습니다.

Terminal

quarto render document.qmd # all formats
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

render 명령은 문서 YAML에 나열된 모든 포맷을 렌더링합니다. 포맷이 지정되지 않았다면 HTML로 렌더링합니다. --to 인수로 특정 포맷만 지정할 수도 있습니다.

Quarto는 어떤 Jupyter 노트북(.ipynb)도 렌더링할 수 있습니다.

Terminal

quarto render document.ipynb

대상 파일(이 경우 document.qmd)은 항상 명령줄의 첫 번째 인수여야 합니다.

.ipynb를 렌더링할 때 Quarto는 기본적으로 노트북 셀을 실행하지 않습니다(노트북을 편집하면서 이미 실행했을 것으로 가정). 셀을 실행하려면 렌더링 시 --execute 플래그를 추가하세요.

Terminal

quarto render notebook.ipynb --execute

워크플로

Julia 코드를 포함한 Quarto 문서는 어떤 텍스트 편집기나 노트북 편집기에서도 작성할 수 있습니다. 어떤 편집 도구를 사용하든, 먼저 quarto preview로 문서 변경 사항을 실시간 미리보기 하는 것이 일반적입니다. 실시간 미리보기는 HTML과 PDF 출력 모두에서 사용할 수 있습니다. 예:

Terminal

# html로 미리보기
quarto preview document.qmd

# pdf로 미리보기
quarto preview document.qmd --to pdf

# jupyter 노트북 미리보기
quarto preview document.ipynb

.ipynb를 렌더링할 때 Quarto는 기본적으로 노트북 셀을 실행하지 않습니다(노트북을 편집하면서 이미 실행했을 것으로 가정합니다). 셀을 실행하려면 렌더링 시 --execute 플래그를 추가하세요.

Terminal

quarto render notebook.ipynb --execute

노트북 YAML front matter에서 이 동작을 지정할 수도 있습니다.

notebook.ipynb

---
title: "My Notebook"
execute: 
  enabled: true
---

노트북 임베딩

Quarto 문서에 실행 가능한 Julia 코드 청크를 포함하는 것 외에도, 외부 Jupyter Notebook(.ipynb)의 셀을 임베드할 수 있습니다. 자세한 내용은 Jupyter Notebook 셀 임베딩을 참고하세요.

Positron

Quarto 확장은 Positron에 포함되어 있으며, .qmd 파일 작업을 위한 다양한 도구를 제공합니다. 이 확장은 Julia Extension과 직접 통합되어 코드 완성, 셀 실행, Quarto 문서의 나란히 미리보기를 제공합니다.

편집기 패널에 소스 마크다운이 표시되고, 뷰어 패널에 렌더링된 문서가 표시된 Positron의 qmd 파일 스크린샷.

이 확장은 명령 팔레트, 단축키 , 또는 편집기 툴바의 Preview 버튼()을 통해 사용할 수 있는 Quarto: Preview 명령을 제공합니다. 렌더링 후 미리보기는 Positron의 Viewer 패널에 표시됩니다.

Positron 사용법에 대한 자세한 내용은 도구: Positron에서 확인하세요.

Positron 노트북 편집기를 사용해 .ipynb 노트북을 만든 뒤 Quarto로 렌더링할 수도 있습니다. Jupyter Lab 섹션에서는 Jupyter Lab에서 Quarto와 노트북을 사용하는 방법을 설명하지만, 동일한 개념이 Positron에도 적용됩니다.

VS Code

VS Code용 Quarto 확장은 .qmd 파일 작업을 위한 다양한 도구를 제공합니다. 이 확장은 Julia Extension과 직접 통합되어 다음과 같은 Julia 전용 기능을 제공합니다.

코드 완성
셀 실행
문맥 기반 도움말

VS Code에 Julia 코드가 포함된 Quarto 문서가 왼쪽에 있고, 오른쪽에는 Julia 코드의 플롯 출력, 하단에는 Quarto Help 패널이 있는 스크린샷.

VS Code 확장은 확장 패널에서 ’quarto’를 검색하거나 확장 마켓플레이스에서 설치할 수 있습니다.

VS Code 노트북 편집기를 사용해 Julia 노트북을 만든 뒤 Quarto로 렌더링할 수도 있습니다. 다음 섹션에서는 Jupyter Lab에서 Quarto로 노트북을 사용하는 방법을 설명하지만, 동일한 개념이 VS Code에도 적용됩니다.

Jupyter Lab

위에서 예로 사용한 간단한 document.qmd를 quarto convert 명령으로 Jupyter 노트북으로 변환할 수 있습니다. 예:

Terminal

quarto convert document.qmd

이 노트북을 Jupyter Lab에서 열고 셀을 실행하면 다음과 같이 보입니다.

왼쪽에는 노트북 미리보기, 오른쪽에는 브라우저의 라이브 미리보기가 나란히 표시된 화면.

여기에는 세 가지 유형의 셀이 있습니다.

맨 위의 YAML 문서 옵션은 Raw 셀에 있습니다.
제목과 설명은 Markdown 셀에 있습니다.
Julia 코드와 그 출력은 Code 셀에 있습니다.

Jupyter 노트북에서 작업할 때는 quarto preview로 렌더링된 문서의 실시간 미리보기를 제공할 수 있습니다.

Terminal

quarto preview document.ipynb

Jupyter Lab에서 노트북을 저장할 때마다 미리보기가 갱신됩니다.

`julia` 엔진 사용하기

설치

julia 엔진은 QuartoNotebookRunner.jl 패키지를 사용해 노트북을 렌더링합니다. julia 엔진으로 노트북을 처음 렌더링할 때 Quarto가 이 패키지를 Quarto 전용 비공개 환경에 자동 설치합니다. 따라서 전역 Julia 환경에 설치할 필요가 없고, 시스템의 다른 Julia 환경에 영향을 주지 않습니다. Quarto는 기본적으로 PATH에 있는 julia 바이너리를 사용하며, QUARTO_JULIA 환경 변수로 변경할 수 있습니다.

QuartoNotebookRunner의 사용자 정의 버전 사용

특수한 경우에는 Quarto가 설치한 QuartoNotebookRunner 버전을 사용하고 싶지 않을 수 있습니다. 예를 들어 QuartoNotebookRunner 자체를 개발 중이거나, 포크/미배포 버전을 써야 하는 경우가 있습니다. 이때는 QuartoNotebookRunner가 설치된 Julia 환경 디렉터리를 환경 변수 QUARTO_JULIA_PROJECT로 지정하세요.

예를 들어 /some/dir에 QuartoNotebookRunner의 main 브랜치를 설치하려면 Julia REPL에서 ]activate /some/dir 후 ]add QuartoNotebookRunner#main을 실행합니다. 서버가 실행 중이 아니라면, 터미널에서 QUARTO_JULIA_PROJECT=/some/dir quarto render some_notebook.qmd처럼 실행하면 해당 커스텀 환경으로 서버 프로세스가 시작됩니다. quarto의 --execute-debug 플래그를 사용해 커스텀 환경이 사용되는지도 확인할 수 있습니다.

`julia` 엔진 활성화

julia 엔진을 사용하려면 명시적으로 활성화해야 합니다. 두 가지 방법이 있습니다.

frontmatter에서 엔진을 지정:

---
title: "A julia engine notebook"
engine: julia
---

```{julia}
1 + 2
```

또는 Quarto 1.7부터는 프로젝트 파일의 engines 배열에 julia를 추가해 프로젝트 전체에서 우선순위를 설정할 수 있습니다(자세한 내용은 엔진 우선순위 참고). 퍼센트 스크립트 파일에서 julia 엔진을 사용하려면 프로젝트 파일 방식이 유일한 옵션입니다.

_quarto.yml

engines: ['julia']

노트북 렌더링

Julia 코드 블록을 포함하고 julia 엔진이 활성화된 노트북을 처음 렌더링하면 QuartoNotebookRunner.jl을 로드하는 지속적인 서버 프로세스가 시작됩니다. 이 패키지는 Quarto 전용 비공개 환경에 자동 설치됩니다.

서버는 렌더링하려는 노트북마다 별도의 Julia worker 프로세스를 실행합니다. 아래 그래프의 보라색 노드 각각은 서버와 통신하는 짧은 수명의 quarto 프로세스와 별개로 실행되는 독립 Julia 프로세스를 나타냅니다.

flowchart LR
    A[<b>quarto render ...</b>] <-.-> B[<b>Server Process</b><br/>QuartoNotebookRunner.jl]
    B <--> C[<b>Worker Process 1</b><br/>notebook_A.qmd]
    B <--> D[<b>Worker Process 2</b><br/>notebook_B.qmd]
    B <--> E[<b>Worker Process 3</b><br/>notebook_C.qmd]

    style A color:#333
    style B fill:#cb9be0,color:#333
    style C fill:#e7d0f2,color:#333
    style D fill:#e7d0f2,color:#333
    style E fill:#e7d0f2,color:#333

call julia engine 명령으로 서버 상태 확인, 종료 요청 등을 할 수 있습니다. 서버는 마지막 worker 프로세스가 종료된 뒤 5분 동안 유지되며, 수동으로 종료하지 않는 한 살아 있습니다. 서버 프로세스에 영향을 주는 환경 변수 변경은 다음 서버 프로세스가 시작될 때만 반영됩니다.

노트북 환경

기본적으로 QuartoNotebookRunner는 worker를 시작할 때 --project=@. 플래그를 사용합니다. 이는 quarto 노트북이 저장된 디렉터리부터 상위 디렉터리로 올라가며 Project.toml 또는 JuliaProject.toml 파일이 있는 환경을 찾도록 합니다.

예를 들어 /some/dir/notebook.qmd의 경우 /some/dir/[Julia]Project.toml, /some/[Julia]Project.toml 등을 찾습니다. 프로젝트 최상위 디렉터리에 환경을 두면, 프로젝트 안의 모든 노트북이 동일한 Julia 환경을 공유하도록 할 수 있습니다.

이 디렉터리들 중 어느 곳에도 환경이 없다면 worker 프로세스는 빈 환경으로 시작하며, 표준 라이브러리만 사용할 수 있습니다.

Note

각 노트북 또는 밀접하게 관련된 노트북 묶음마다 별도의 환경을 만드는 것이 모범 사례입니다. 너무 많은 노트북이 하나의 환경(예: Julia가 기본으로 로드하는 공유 환경)을 공유하면, 환경 변경 시 의도치 않게 일부 노트북이 깨질 가능성이 높습니다.

Julia 환경을 만드는 방법은 여러 가지가 있으며, 자세한 내용은 공식 문서를 참고하세요. 간단한 방법으로는 노트북에 Pkg 설치 명령을 추가한 뒤 한 번 실행하는 것입니다. 이후 해당 명령을 삭제하면 노트북 디렉터리에 환경을 나타내는 Project.toml과 Manifest.toml이 생성됩니다.

---
engine: julia
---

```{julia}
using Pkg
Pkg.add("DataFrames")
```

또 다른 방법은 터미널에서 julia를 실행해 REPL을 열고, ]를 눌러 Pkg REPL 모드로 전환하는 것입니다. 이 모드에서 activate /some/dir로 환경을 활성화한 뒤 add DataFrames 명령으로 패키지를 설치합니다.

노트북 디렉터리를 환경으로 사용하지 않으려면 frontmatter의 exeflags에서 --project 플래그로 다른 디렉터리를 지정할 수 있습니다.

---
engine: julia
julia:
  exeflags: ["--project=/some/other/dir"]
---

Worker 프로세스 재사용

기본적으로 유휴 worker 프로세스는 5분 동안 유지됩니다. daemon 키에 원하는 초 단위 값을 전달해 변경할 수 있습니다.

---
title: "A julia notebook with ten minutes timeout"
engine: julia
execute:
  daemon: 600
---

노트북을 다시 렌더링할 때는 이미 의존성이 로드된 worker 프로세스를 재사용하므로 지연이 줄어듭니다. 가능한 범위 내에서 QuartoNotebookRunner.jl은 이전 실행의 리소스를 가비지 컬렉터에 해제합니다. 각 실행에서 코드는 새로운 모듈에 평가되므로 이전 실행에서 정의된 변수와 충돌하지 않습니다. 다만 패키지 런타임 설정 변경이나 함수 메서드의 추가/삭제 같은 상태 변화는 실행 간에 유지됩니다. 필요하다면 --execute-daemon-restart 플래그로 노트북 worker 프로세스를 강제로 재시작할 수 있습니다.

또는 데몬을 비활성화해 렌더링마다 새 프로세스를 사용하도록 할 수 있습니다(패키지 재로드로 지연이 늘어납니다).

execute:
  daemon: false

서버 프로세스 자체는 worker 프로세스가 더 이상 없으면 5분 후 타임아웃됩니다.

엔진 옵션

엔진 옵션은 julia 최상위 키 아래에 전달할 수 있습니다.

---
title: "A julia engine notebook"
engine: julia
julia:
  key: value
---

현재 사용 가능한 옵션은 다음과 같습니다.

exeflags: worker 프로세스를 시작하는 julia 명령에 추가되는 문자열 배열입니다. 예를 들어 기본값은 --project=@.(노트북이 저장된 디렉터리의 환경)이며, exeflags: ["--project=/some/directory/"]로 덮어쓸 수 있습니다.
env: worker 프로세스에 전달할 환경 변수를 문자열 배열로 지정합니다. 예: env: ["SOMEVAR=SOMEVALUE"].

`quarto call engine julia` 명령

Quarto 1.7부터 julia 엔진은 quarto call engine julia 엔트리포인트를 통해 설정 및 모니터링용 CLI 명령을 제공합니다.

`status`

status 명령은 현재 실행 중인 서버 프로세스와 worker 프로세스에 대한 정보를 출력합니다. 예:

$ quarto call engine julia status
QuartoNotebookRunner server status:
  started at: 9:44:31 (47 seconds ago)
  runner version: 0.15.0
  environment: /Users/username/Library/Caches/quarto/julia/
  pid: 42008
  port: 8000
  julia version: 1.11.4
  timeout: 5 minutes
  workers active: 1
    worker 1:
      path: /Users/username/notebook.qmd
      run started: 9:44:38 (40 seconds ago)
      run finished: -
      timeout: 5 minutes
      pid: 42026
      exe: `julia`
      exeflags: ["--color=yes"]
      env: ["JULIA_PROJECT=@."]

`close`

close 명령은 노트북 worker 프로세스를 종료합니다. 기본적으로는 유휴 worker 프로세스만 종료할 수 있습니다. run finished 상태가 채워진 worker가 유휴 상태입니다. 이 경우 close를 호출할 수 있습니다.

$ quarto call engine julia status
QuartoNotebookRunner server status:
  started at: 9:44:31 (5 minutes 41 seconds ago)
  runner version: 0.15.0
  environment: /Users/username/Library/Caches/quarto/julia/
  pid: 42008
  port: 8000
  julia version: 1.11.4
  timeout: 5 minutes
  workers active: 1
    worker 1:
      path: /Users/username/notebook.qmd
      run started: 9:44:38 (5 minutes 34 seconds ago)
      run finished: 9:46:21 (took 1 minute 43 seconds)
      timeout: 5 minutes (1 minute 9 seconds left)
      pid: 42026
      exe: `julia`
      exeflags: ["--color=yes"]
      env: ["JULIA_PROJECT=@."]

$ quarto call engine julia close /Users/username/notebook.qmd
Worker closed successfully.

무한 루프 등으로 멈춘 worker를 강제로 종료하려면 --force 플래그를 추가합니다. 이 플래그는 작업 중인 내용이 모두 손실되며, 다음 실행 시 worker가 새로 시작되고 패키지 로딩이 다시 이루어집니다.

$ quarto call engine julia status                                                     
QuartoNotebookRunner server status:
  started at: 11:2:40 (16 seconds ago)
  runner version: 0.15.0
  environment: /Users/username/Library/Caches/quarto/julia/
  pid: 50642
  port: 8000
  julia version: 1.11.4
  timeout: 5 minutes
  workers active: 1
    worker 1:
      path: /Users/username/notebook.qmd
      run started: 11:2:47 (9 seconds ago)
      run finished: -
      timeout: 5 minutes
      pid: 50650
      exe: `julia`
      exeflags: ["--color=yes"]
      env: ["JULIA_PROJECT=@."]

$ quarto call engine julia close /Users/username/notebook.qmd
ERROR: Julia server returned error after receiving "close" command:

Failed to close notebook: /Users/username/notebook.qmd

The underlying Julia error was:

Tried to close file "/Users/username/notebook.qmd" but the corresponding worker is busy.

Stack trace:
  [omitted for brevity]

$ quarto call engine julia close --force /Users/username/notebook.qmd
Worker force-closed successfully.

$ quarto call engine julia status                                                     
QuartoNotebookRunner server status:
  started at: 11:2:40 (46 seconds ago)
  runner version: 0.15.0
  environment: /Users/username/Library/Caches/quarto/julia/
  pid: 50642
  port: 8000
  julia version: 1.11.4
  timeout: 5 minutes (4 minutes 56 seconds left)
  workers active: 0

`stop`

stop 명령은 서버 프로세스를 정상 종료합니다. worker가 작업 중이면 오류가 발생합니다.

$ quarto call engine julia status
QuartoNotebookRunner server status:
  started at: 11:2:40 (3 minutes 43 seconds ago)
  runner version: 0.15.0
  environment: /Users/username/Library/Caches/quarto/julia/
  pid: 50642
  port: 8000
  julia version: 1.11.4
  timeout: 5 minutes (1 minute 59 seconds left)
  workers active: 0

$ quarto call engine julia stop 
Server stopped.

$ quarto call engine julia status
Julia control server is not running.

`kill`

kill 명령은 서버 프로세스를 강제 종료합니다. 서버가 불안정하거나 응답하지 않을 때의 마지막 수단으로 사용합니다. 이 명령은 모든 worker 프로세스도 종료하므로 진행 중인 작업이 모두 손실됩니다.

`log`

log 명령은 서버 프로세스의 내부 로그 파일 출력을 표시합니다. 서버가 시작에 실패하거나 예기치 않게 종료되는 경우 이 로그 파일에 유용한 정보가 있을 수 있습니다.

`juliaup` 통합

juliaup는 Julia 버전을 설치하고 관리하는 권장 방법입니다. julia 엔진은 juliaup의 + 채널 지정자를 사용해 노트북이 사용하는 Julia 버전을 선택할 수 있도록 지원합니다. 이를 통해 PATH를 변경하지 않고도 같은 머신에서 서로 다른 Julia 버전으로 여러 노트북을 동시에 실행할 수 있습니다.

이 기능을 사용하려면 juliaup으로 사용할 채널을 설치한 뒤, 노트북 frontmatter의 julia.exeflags 옵션에 채널 지정자를 추가하세요.

---
title: "A Julia 1.11 notebook"
engine: julia
julia:
  exeflags: ["+1.11"]
---

```{julia}
VERSION
```

QuartoNotebookRunner는 현재 Julia 1.6 이상을 지원합니다. 더 낮은 버전을 지원할 계획은 없습니다.

Revise.jl 통합

Revise는 Julia 세션에서 함수 정의를 자동으로 업데이트합니다. 이는 자체 패키지나 대규모 프로젝트를 개발하는 Julia 사용자에게 필수적인 도구입니다. julia 엔진은 노트북 시작 셀에서 Revise를 import하면 해당 노트북 프로세스에서 사용할 수 있도록 지원합니다. Revise는 Julia REPL과 동일하게 로컬 패키지에서 가져온 함수 정의를 자동으로 업데이트합니다.

노트북이 사용하는 프로젝트 환경에 Revise가 설치되어 있어야 합니다. Julia는 글로벌 환경을 로드 경로에 포함하지 않기 때문입니다(이는 Julia REPL과 다른 동작입니다).

캐싱

이 엔진에는 노트북 결과 캐싱이 내장되어 있습니다. 기본적으로는 비활성화되어 있으며, 노트북 frontmatter에서 execute.cache 옵션을 true로 설정해 활성화할 수 있습니다.

---
title: "A caching example"
engine: julia
execute:
  cache: true
---

```{julia}
rand()
```

노트북 캐시는 다음 기준으로 무효화됩니다.

다른 Julia 버전으로 노트북을 실행한 경우.
노트북 환경의 Manifest.toml 변경(패키지 추가/제거/버전 변경 포함).
노트북 frontmatter의 변경.
실행 가능한 Julia 셀의 콘텐츠 변경(셀 옵션 포함).

캐시를 무효화하지 않는 변경:

실행 가능한 Julia 셀 밖의 마크다운 콘텐츠 편집.

캐시는 노트북 파일 옆의 .cache 디렉터리에 저장됩니다. 이 디렉터리를 삭제하면 모든 캐시가 무효화됩니다. 개별 캐시 파일의 내용은 내부 구현 세부 사항이므로 의존하지 마세요.

이 캐시는 GitHub Actions의 action/cache 같은 도구를 통해 CI에 저장해, 변경이 잦지 않은 장시간 실행 노트북의 렌더링 시간을 개선할 수 있습니다.

R과 Python 지원

julia 엔진은 RCall과 PythonCall 패키지 통합을 통해 {r} 및 {python} 실행 코드 블록을 지원합니다. 이 기능을 사용하려면 노트북 작성자가 {julia} 셀에서 해당 패키지를 명시적으로 import해야 합니다. 그 이후 {r} 및 {python} 셀을 사용할 수 있습니다.

---
title: "Multi-language notebooks"
engine: julia
---

```{julia}
import PythonCall
import RCall
```

Create some data in Julia:

```{julia}
data = sin.(0:0.1:4pi)
```

Then plot it in R by interpolating the `data` variable from Julia into `R` via
the `$` syntax:

```{r}
plot($data)
```

The same `$` syntax can be used to interpolate Julia variables into Python code as well:

```{python}
len($data)
```

엔진 “확장”

QuartoNotebookRunner 구현은 외부 Julia 패키지를 통해 노트북 동작을 확장할 수 있게 합니다.

예를 들어 QuartoTools.jl 패키지는 세밀한 함수 호출 캐싱, 노트북 프로세스와 일반 julia 프로세스 간 데이터 직렬화 지원, 노트북에서 프로그램적으로 셀 입력/출력을 생성할 수 있는 “확장 가능한” 셀 출력을 제공합니다. 자세한 내용은 링크된 문서를 참고하세요.

이와 같은 접근은 다른 서드파티 패키지에도 적용할 수 있습니다. 이 기능에 대한 문의나 요청은 QuartoNotebookRunner 저장소로 보내세요.

`jupyter` 엔진 사용하기

설치

Julia 코드가 포함된 문서를 렌더링하려면 다음 구성 요소를 설치해야 합니다.

IJulia
Revise.jl
선택적으로 Jupyter Cache

아래에서 각각을 다룹니다.

IJulia

IJulia는 Julia 언어용 Jupyter 실행 커널입니다. Julia REPL에서 다음과 같이 설치할 수 있습니다.

using Pkg
Pkg.add("IJulia")
using IJulia
notebook()

notebook()을 처음 실행하면 Jupyter를 설치할지 묻습니다. Enter를 누르면 Conda.jl 패키지를 사용해 최소 Python+Jupyter 배포판(Miniconda)을 설치합니다. 이 배포판은 Julia 전용이며 PATH에 추가되지 않습니다. Linux에서는 먼저 PATH에서 jupyter를 찾고, 실패하면 Conda Jupyter 설치를 묻습니다.

Conda.jl로 Python과 Jupyter를 설치하지 않겠다면, 시스템에 다른 Jupyter 설치가 있어야 합니다(필요하면 Jupyter 설치 섹션을 참고하세요).

Revise.jl

IJulia 외에도 Revise.jl을 설치하고 IJulia와 함께 사용하도록 설정하는 것을 권장합니다. Revise.jl은 Julia 세션을 오래 유지해 코드 변경 시 재시작을 줄여주는 라이브러리입니다.

Quarto는 반복 작업에서 Jupyter 시작 시간을 줄이기 위해 문서마다 지속적인 커널 데몬을 유지합니다. Revise.jl은 이 지속 프로세스가 패키지 업데이트, git 브랜치 변경 등에 강하도록 만들어 줍니다. Revise.jl은 다음과 같이 설치합니다.

using Pkg
Pkg.add("Revise")

IJulia에서 Revise가 자동으로 로드되도록 .julia/config/startup_ijulia.jl 파일을 다음 내용으로 생성하세요.

try
  @eval using Revise
catch e
  @warn "Revise init" exception=(e, catch_backtrace())
end

Revise.jl에 대한 자세한 내용은 https://timholy.github.io/Revise.jl/stable를 참고하세요.

Jupyter Cache

Jupyter Cache는 노트북의 모든 셀 출력을 캐시합니다. 노트북의 셀 중 하나라도 변경되면 모든 셀이 다시 실행됩니다.

IJulia.notebook()이 설치한 통합 Jupyter를 사용하는 경우, IJulia가 관리하는 Python 환경에 jupyter-cache를 추가해야 합니다. 다음과 같이 추가할 수 있습니다.

using Conda
Conda.add("jupyter-cache")

또는 IJulia가 관리하지 않는 다른 Python의 Jupyter를 사용한다면, 아래 Jupyter 설치 섹션의 jupyter cache 설치 안내를 참고하세요.

캐싱

Jupyter Cache는 노트북의 모든 셀 출력을 캐시할 수 있게 해줍니다. 노트북의 어떤 셀이든 변경되면 모든 셀이 다시 실행됩니다.

Jupyter Cache를 사용하려면 먼저 jupyter-cache 패키지를 설치해야 합니다.

플랫폼	명령
Mac/Linux	Terminal `python3 -m pip install jupyter-cache`
Windows	Terminal `py -m pip install jupyter-cache`

문서에 캐시를 활성화하려면 cache 옵션을 추가합니다. 예:

---
title: "My Document"
format: html
execute: 
  cache: true
---

프로젝트 수준에서도 캐싱을 지정할 수 있습니다. 예:

project:
  type: website
  
format:
  html:
    theme: united
    
execute:
  cache: true

코드 셀 밖의 변경(예: 마크다운 서술)은 문서 캐시를 무효화하지 않습니다. 그래서 문서의 글쓰기 부분만 작업할 때 캐싱은 매우 편리합니다.

Jupyter Cache에는 노트북 캐시를 분석하고 관리할 수 있는 jcache 명령줄 유틸리티가 포함되어 있습니다. 자세한 내용은 Jupyter Cache 문서를 참고하세요.

렌더링

quarto render 명령줄 옵션으로 문서 코드를 변경하지 않고 캐싱 동작을 제어할 수 있습니다. 모든 청크에 캐시를 강제로 사용하거나, 옵션에 지정되어 있더라도 캐시를 비활성화하거나, 캐시가 무효화되지 않았더라도 강제로 새로고침할 수 있습니다.

Terminal

# 캐시 사용(옵션에 활성화되어 있지 않아도)
quarto render example.qmd --cache 

# 캐시 사용 안 함(옵션에 활성화되어 있어도)
quarto render example.qmd --no-cache 

# 캐시 사용 + 강제 새로고침 
quarto render example.qmd --cache-refresh

대안

렌더링 시간이 길어 캐싱을 고려한다면, 캐싱 외에도 아래 대안을 함께 고려할 수 있습니다.

실행 비활성화

서술/마크다운 작업만 하고 있다면 실행을 완전히 비활성화하는 것이 좋습니다. enabled: false 실행 옵션으로 설정합니다. 예:

---
title: "My Document"
format: html
execute: 
  enabled: false
---

Jupyter .ipynb 노트북으로 작성하는 경우(일반 텍스트 .qmd가 아닌), 이는 이미 기본 동작입니다. 즉, quarto render를 호출해도 실행은 되지 않고, 노트북에서 작업할 때 실행이 이루어집니다.

실행 고정

프로젝트에서 여러 문서를 한꺼번에 렌더링할 때 누적 비용이 걱정된다면 freeze 옵션을 고려하세요.

freeze 옵션을 사용하면 전체 프로젝트 렌더링 중 계산 문서를 다시 렌더링하지 않도록 하거나, 소스 파일이 변경될 때만 다시 렌더링하도록 지정할 수 있습니다.

execute:
  freeze: true  # 프로젝트 렌더링 중 다시 렌더링하지 않음

execute:
  freeze: auto  # 소스가 변경될 때만 다시 렌더링

freeze는 전체 프로젝트 렌더링 중 실행 여부를 제어합니다. 단일 문서나 프로젝트 하위 디렉터리를 증분 렌더링하면 코드는 항상 실행됩니다. 예:

Terminal

# 단일 문서 렌더링(항상 코드 실행)
quarto render document.qmd

# 프로젝트 하위 디렉터리 렌더링(항상 코드 실행)
quarto render articles

프로젝트에서 freeze를 사용하는 방법은 프로젝트 실행 관리 문서를 참고하세요.

커널 선택

첫 번째 예시에서 julia-1.8 커널을 문서 옵션에 명시한 것을 볼 수 있습니다(간략화를 위해 축약).

---
title: "StatsPlots Demo"
jupyter: julia-1.8
---

jupyter 커널을 명시하지 않으면 Quarto가 시스템에서 Julia를 지원하는 커널을 자동으로 찾습니다.

시스템에 사용 가능한 Jupyter 커널은 quarto check 명령으로 확인할 수 있습니다.

Terminal

quarto check jupyter

커널 데몬

Jupyter 커널의 시작 시간을 줄이기 위해 Quarto는 각 문서에 대해 실행 중인 Jupyter 커널을 유지하는 데몬을 사용합니다. 이를 통해 이후 렌더링이 커널 시작을 기다리지 않고 즉시 진행됩니다.

데몬은 대화형 세션에서 렌더링 반응성을 높이기 위한 것입니다. 따라서 활성 tty 없이 렌더링하거나 배치 렌더링(예: Quarto 프로젝트)의 일부일 때는 데몬이 생성되지 않습니다.

Quarto는 Windows에서 기본적으로 데몬을 사용하지 않습니다(일부 Windows 시스템은 데몬에 필요한 소켓 연결을 허용하지 않기 때문입니다).

이 동작은 daemon 실행 옵션으로 사용자 정의할 수 있습니다. false로 설정하면 데몬을 사용하지 않으며, 초 단위 값을 지정하면 해당 시간이 지나면 데몬이 타임아웃됩니다(기본값은 300초). 예:

execute:
  daemon: false

execute:
  daemon: 60

Windows에서 데몬을 사용하려면 명시적으로 활성화해야 합니다.

execute:
  daemon: true

명령줄

다음 명령줄 옵션으로 Jupyter 데몬 사용을 제어할 수도 있습니다.

Terminal

# 기본 타임아웃(300초)으로 데몬 사용
quarto render document.qmd --execute-daemon

# 명시적 타임아웃으로 데몬 사용
quarto render document.qmd --execute-daemon 60

# 데몬 사용하지 않기
quarto render document.qmd --no-execute-daemon

--execute-daemon-restart 플래그로 기존 데몬을 강제로 재시작할 수도 있습니다.

Terminal

quarto render document.qmd --execute-daemon-restart

노트북 세션 재사용이 오류를 일으킨다고 의심될 때 유용합니다.

마지막으로 --execute-debug 플래그로 데몬 사용에 대한 상세한 디버깅 정보(시작/종료/연결 등)를 출력할 수 있습니다.

Terminal

quarto render document.qmd --execute-debug

Jupyter 설치

IJulia가 자동으로 설치하는 최소 Python/Jupyter를 사용할 수도 있고, 별도로 Python과 Jupyter를 설치할 수도 있습니다. 다른 Jupyter 버전을 설치해야 하는 경우 이 섹션을 참고하세요.

시스템에 아직 Python 3가 없다면, https://www.python.org/downloads/의 표준 설치 프로그램으로 설치하는 것을 권장합니다.

새 Python 3 환경이라면 jupyter 패키지를 설치하면 Quarto에서 Jupyter 커널을 실행하는 데 필요한 모든 구성 요소가 제공됩니다.

패키지 관리자 \| 명령 \|
Pip (Mac/Linux)	Terminal `python3 -m pip install jupyter`
Pip (Windows)	Terminal `py -m pip install jupyter`
Conda	Terminal `conda install jupyter`

다음 명령으로 Quarto의 Jupyter 구성이 올바른지 확인할 수 있습니다.

Terminal

quarto check jupyter

Quarto는 Windows에서 Python Launcher를, macOS와 Linux에서는 시스템 PATH를 사용해 Python 버전을 선택합니다. Quarto가 사용하는 Python 버전은 QUARTO_PYTHON 환경 변수를 설정해 변경할 수 있습니다.

가상 환경을 사용 중이라면 가상 환경을 참고하세요.

Jupyter Cache

Jupyter Cache는 노트북의 모든 셀 출력을 캐시합니다. 노트북의 셀 중 하나라도 변경되면 모든 셀이 다시 실행됩니다.

Jupyter Cache를 사용하려면 먼저 jupyter-cache 패키지를 설치해야 합니다.

플랫폼	명령
Mac/Linux	Terminal `python3 -m pip install jupyter-cache`
Windows	Terminal `py -m pip install jupyter-cache`
Conda	Terminal `conda install jupyter-cache`

캐시를 활성화하려면 cache 옵션을 추가합니다. 예를 들어:

개요

코드 블록

다중 출력

렌더링

워크플로

노트북 임베딩

Positron

VS Code

Jupyter Lab

julia 엔진 사용하기

설치

julia 엔진 활성화

노트북 렌더링

노트북 환경

Worker 프로세스 재사용

엔진 옵션

quarto call engine julia 명령

status

close

stop

kill

log

juliaup 통합

Revise.jl 통합

캐싱

R과 Python 지원

엔진 “확장”

jupyter 엔진 사용하기

설치

IJulia

Revise.jl

Jupyter Cache

캐싱

렌더링

대안

실행 비활성화

실행 고정

커널 선택

커널 데몬

명령줄

Jupyter 설치

Jupyter Cache

`julia` 엔진 사용하기

`julia` 엔진 활성화

`quarto call engine julia` 명령

`status`

`close`

`stop`

`kill`

`log`

`juliaup` 통합

`jupyter` 엔진 사용하기