Quarto에서 Binder 사용

개요

Binder 프로젝트는 컴퓨팅 환경을 쉽게 공유할 수 있도록 설계된 도구 모음을 제공합니다. Binder를 사용하면 컴퓨팅 환경을 복원하는 링크를 쉽게 제공할 수 있고, 사용자가 프로젝트 코드를 상호작용하며 사용할 수 있습니다.

Quarto 프로젝트에서 Binder를 사용하려면 컴퓨팅 환경을 설명하는 구성 파일 세트를 포함해야 합니다. Quarto는 quarto use binder 명령으로 이 파일들을 자동으로 만들 수 있습니다. Quarto 프로젝트 디렉터리에서 명령을 실행하면 프로젝트를 스캔해 환경 복원에 필요한 구성 파일을 결정합니다. 생성된 파일을 프로젝트 저장소에 커밋하면 프로젝트가 Binder 준비 완료 상태가 됩니다.

이 과정을 자세히 보려면 계속 읽고, 의존성 지정, 생성될 수 있는 구성 파일, 문서에 Binder 링크 추가 방법을 알고 싶다면 해당 섹션으로 넘어가세요.

단계별 안내

_quarto.yml과 R 실행 코드 셀을 포함한 histogram.qmd 문서가 있는 Quarto 프로젝트를 예로 들어보겠습니다.

histogram.qmd
---
title: Histogram
---

```{r}
hist(rnorm(100))
```

이 프로젝트의 환경을 만들려면 Binder가 Quarto와 R을 설치해야 하며, 로컬에서 프로젝트를 빌드할 때 사용한 Quarto와 R 버전과 동일한 버전을 사용해야 합니다. 환경에 IDE를 추가하는 것도 좋습니다. .qmd 문서에 R 코드 셀이 있다면 RStudio가 좋은 선택입니다.

요구 사항을 설명하는 파일을 Quarto가 생성하도록 하려면 프로젝트 디렉터리에서 다음을 실행합니다.

Terminal
quarto use binder

이 명령은 먼저 프로젝트 구성을 감지해 보고합니다.

[✓] Detected Project configuration:

    Quarto       most recent prerelease
    JupyterLab   default               
    Engine       knitr                 
    R            4.3.2 (2023-10-31)    
    Editor       rstudio               

No files which provide dependencies were discovered. If you continue, no dependencies will be restored when running this project with Binder.

Learn more at:
https://www.quarto.org/docs/prerelease/1.4/binder.html#dependencies

? Do you want to continue? (Y/n) ›

Quarto는 사용 중인 Quarto와 R 버전, 문서의 Knitr 엔진 사용 여부를 감지하고 프로젝트에 적합한 편집기를 선택합니다.

Quarto는 R, Python, Julia 의존성을 설명하는 파일도 감지합니다. 자세한 내용은 아래 의존성에서 확인할 수 있습니다. 이 프로젝트는 R 코드에 추가 패키지가 필요 없으므로 해당 파일이 없습니다.

계속 진행하면 Quarto가 생성할 파일 목록을 보여줍니다.

The following files will be written:
┌─────────────┬────────────────────────────────────────┐
│ postBuild   │ Configures Quarto and supporting tools │
├─────────────┼────────────────────────────────────────┤
│ apt.txt     │ Installs Quarto required packages      │
├─────────────┼────────────────────────────────────────┤
│ runtime.txt │ Installs R and configures RStudio      │
└─────────────┴────────────────────────────────────────┘

 ? Continue? (Y/n) ›

마지막 확인 후 Quarto가 이 파일들을 프로젝트에 작성합니다.

Writing configuration files
[✓] postBuild
[✓] apt.txt
[✓] runtime.txt

이 구성 파일은 프로젝트 파일과 함께 프로젝트 저장소에 커밋해야 합니다.

mybinder.org에서 프로젝트 저장소 링크를 제공하면 Binder가 구성 파일로 컴퓨팅 환경을 빌드하고, 사용자가 그 환경에서 저장소 내용을 상호작용할 수 있는 링크를 제공합니다.

다음 Binder URL로 이 프로젝트의 Binder를 시험해 볼 수 있습니다. https://mybinder.org/v2/gh/cwickham/binder-example/HEAD?urlpath=rstudio

이 링크 끝의 ?urlpath=rstudio는 RStudio 세션을 열겠다는 의미입니다. Binder 환경은 시작에 시간이 조금 걸릴 수 있지만, 시작되면 프로젝트가 열린 RStudio 인스턴스에 들어가게 됩니다. 컴퓨팅 환경이 구성되어 있으므로 일반적인 방법(RStudio 인터페이스 또는 터미널의 quarto render)으로 프로젝트를 렌더링할 수 있습니다.

프로젝트가 사용하는 언어와 엔진에 따라 Quarto는 이 프로젝트에 표시된 것 외의 파일을 생성할 수 있습니다. quarto use binder가 생성할 수 있는 파일은 아래 구성 파일에서 더 알아볼 수 있습니다.

대부분의 프로젝트에는 R, Python, Julia 패키지 같은 추가 의존성이 있습니다. 앞서 언급했듯이 Quarto는 이러한 의존성을 지정하는 일반적인 파일을 감지할 수 있습니다. 이 파일들에 대해서는 아래 의존성에서 자세히 설명합니다.

의존성

Binder로 프로젝트를 새 컴퓨팅 환경에 복원할 때는 프로젝트의 의존성도 함께 복원되어야 합니다. quarto use binder 명령은 Quarto 문서 내부의 계산 의존성을 감지하지는 않지만, 이를 설명하는 일반적인 파일은 감지합니다. 각 환경에서 이를 설명하는 가장 일반적인 방법은 다음과 같습니다.

Language Environment File
R renv renv.lock
R Binder R Config install.R
Python Conda environment.yml
Python Pip requirements.txt
Julia Pkg project.toml

이 파일들은 가상 환경을 사용하는 과정에서 생성되는 경우가 많습니다. Quarto에서 가상 환경을 사용하는 방법은 가상 환경 문서를 참고하세요.

구성 파일

다음 파일은 quarto use binder 명령으로 생성될 수 있습니다. 이 명령은 자신이 생성하지 않은 사용자 파일이나 생성 후 수정된 파일을 덮어쓰기 전에 확인을 요청합니다.

postBuild

post build 스크립트는 환경 복원 후에 코드를 실행합니다. 이 스크립트는 환경에 적절한 Quarto 버전이 존재하도록 보장하고, TinyTex나 Chromium 같은 필요한 도구를 설치하며, 해당되는 경우 VSCode와 Quarto 확장을 구성하기 위한 명령으로 생성됩니다.

apt.txt

apt-get으로 설치할 Debian 패키지 목록을 제공합니다. 이 파일은 Quarto 패키지 의존성을 모두 포함하도록 생성됩니다.

runtime.txt

R 프로젝트의 경우 적절한 R 버전이 포함된 이 파일이 생성되며, 컴퓨팅 환경에 동일한 R 버전이 존재하도록 보장합니다. 또한 사용자가 컴퓨팅 환경을 복원할 때 RStudio가 구성되고 사용할 수 있게 됩니다.

install.R

R 프로젝트의 경우 install.R 파일이 생성되어 존재하는 renv 환경을 활성화합니다.

.jupyter

Jupyter 엔진을 사용하는 QMD 파일 프로젝트의 경우, JupyterLab 환경에서 VSCode 지원을 구성하는 .jupyter 디렉터리가 생성됩니다.

Binder가 이 구성 파일을 어떻게 사용하는지는 Binder 문서에서 더 알아볼 수 있습니다.

Tip

quarto use binder 명령으로 생성된 파일은 Binder가 저장소를 사용해 컴퓨팅 환경을 복원할 때 필요하므로, 저장소에 커밋해야 합니다.

Binder 링크 추가

프로젝트가 GitHub에 호스팅되어 있다면 문서 YAML에 code-links: binder를 추가해 Binder 링크를 표시할 수 있습니다.

histogram.qmd
---
title: Histogram
code-links: binder
---

렌더링하면 Code Links 아래에 “Launch Binder” 링크가 표시됩니다.

Screenshot of the Code Links section on a rendered HTML page showing a link with the text Launch Binder.

원고 프로젝트라면 원고 구성에 code-links: binder를 사용해 원고 웹페이지에 링크를 표시할 수도 있습니다.

_quarto.yml
manuscript:
  code-links: binder