Bundler 모듈

Bundler 모듈

Bundler는 필요한 정확한 gem과 버전을 추적·설치해 Ruby 프로젝트에 일관된 환경을 제공해요. Bundler는 Ruby 표준 라이브러리의 일부예요.

모든 프로젝트 의존성과 (선택적으로) 그 버전을 나열한 Gemfile을 만들고, require 'bundler/setup' 또는 Bundler.setup을 사용해 지정된 gem과 지정된 버전만 사용할 수 있는 환경을 설정하는 방식으로 쓰여요.

Gemfile 생성과 Bundler 사용법에 대한 광범위한 문서는 Bundler 웹사이트를 참고하세요. 프로젝트 안의 표준 라이브러리로서 Bundler는 로드되고 require된 모듈의 내부(introspection)를 들여다보는 데도 쓸 수 있어요.

출처: Ruby 3.3 API

본문

Public Class Methods

app_cache(custom_path = nil)

사용자 지정 경로(없으면 프로젝트 루트) 아래의 어플리케이션 캐시 경로를 반환해요.

# File lib/bundler.rb, line 347
def app_cache(custom_path = nil)
  path = custom_path || root
  Pathname.new(path).join(settings.app_cache_path)
end

app_config_path()

Bundler 어플리케이션 설정 경로를 반환해요. BUNDLE_APP_CONFIG 환경 변수를 우선적으로 사용해요.

# File lib/bundler.rb, line 333
def app_config_path
  if app_config = ENV["BUNDLE_APP_CONFIG"]
    app_config_pathname = Pathname.new(app_config)

    if app_config_pathname.absolute?
      app_config_pathname
    else
      app_config_pathname.expand_path(root)
    end
  else
    root.join(".bundle")
  end
end

auto_install()

Bundler.settings[:auto_install]이 존재하면 의존성을 자동으로 설치해요. (bundle config set --global auto_install 1으로 설정돼요.) 이 메서드는 전역 Definition 객체를 nil로 만들어 버리므로, 옛 객체에 대한 참조를 유지하는 Installer 같은 것을 인스턴스화하기 전에 먼저 호출해야 해요.

# File lib/bundler.rb, line 180
def auto_install
  return unless settings[:auto_install]
  # ... (설치 로직)
end

auto_switch()

사용 중인 gemfile에 따라 자동으로 버전을 전환하도록 하는 동작과 관련된 메서드예요.

bin_path()

Bundler의 바이너리 경로를 반환해요.

bundle_path()

번들된 gem이 설치되는 기본 경로를 반환해요.

clean_env()

Bundler 관련 환경 변수를 제거한 깨끗한 환경 해시를 반환해요. (with_clean_env 참고.)

clean_exec(*args)

Bundler가 없는 깨끗한 환경에서 명령을 exec 해요.

clean_system(*args)

Bundler가 없는 깨끗한 환경에서 시스템 명령을 실행해요.

clear_gemspec_cache()

gemspec 캐시를 비워요.

configure()

Bundler를 Ruby 환경에 맞게 구성해요. gem 경로, 홈, 바이너리 경로 등을 설정하는 핵심 메서드예요.

# File lib/bundler.rb, line 115 : (구성 로직 — configure_gem_home_and_path, configure_gem_path 등 호출)
def configure
  configure_gem_home_and_path
  configure_gem_path
end

configure_gem_home_and_path(path = bundle_path)

gem home과 path를 설정해요.

configured_bundle_path()

설정된 bundle 경로를 반환해요.

create_bundle_path()

bundle 경로를 생성해요.

default_bundle_dir()

기본 bundle 디렉터리를 반환해요.

default_gemfile()

기본 Gemfile 경로([Directory]Gemfile로 탐색)를 반환해요.

default_lockfile()

기본 lockfile 경로(Gemfile에 .lock을 더한 것)를 반환해요.

definition(unlock = nil, lockfile = default_lockfile)

Definition 객체를 생성·캐시해 반환해요. unlock이 주어지면 그에 따라 unlock 처리를 해요.

environment()

Bundler.load로 대체된 메서드예요. Bundler.load를 호출하며 deprecation 경고를 출력해요.

# File lib/bundler.rb, line 219
def environment
  SharedHelpers.major_deprecation 2, "Bundler.environment has been removed in favor of Bundler.load", print_caller_location: true
  load
end

feature_flag()

Bundler::FeatureFlag 인스턴스를 반환해요 (기능 플래그 접근).

frozen_bundle?()

bundle이 동결(frozen) 상태인지 반환해요.

git_present?()

git이 설치되어 있는지 반환해요.

home()

Bundler 홈 디렉터리 경로를 반환해요.

install_path()

설치 경로를 반환해요.

load()

Gemfile에서 Bundler::Environment를 로드해 반환해요.

load_gemspec(file, validate = false)

gemspec 파일을 로드해 반환해요 (캐시 사용).

load_gemspec_uncached(file, validate = false)

gemspec 파일을 캐시 없이 직접 로드해 반환해요.

local_platform()

현재 로컬 플랫폼(Gem::Platform.local)을 반환해요.

locked_gems()

lockfile에 기록된 gem 목록을 반환해요.

mkdir_p(path)

경로를 재귀적으로 생성해요 (FileUtils.mkdir_p 래퍼).

most_specific_locked_platform?(platform)

주어진 플랫폼이 가장 구체적으로 잠긴 플랫폼인지 반환해요.

original_env()

원래(변경 전) 환경 해시를 반환해요.

original_exec(*args)

원래 환경에서 명령을 exec 해요.

original_system(*args)

원래 환경에서 시스템 명령을 실행해요.

preferred_gemfile_name()

선호하는 Gemfile 이름(Gemfile 또는 gems.rb)을 반환해요.

read_file(file)

Bundler의 루트 인코딩을 기준으로 파일을 읽어 반환해요.

require(*groups)

아직 설정되지 않았다면 Bundler 환경을 설정(Bundler.setup 참고)하고, 지정된 그룹의 모든 gem을 로드해요. ::setup과 달리, (setup이 허용한 그룹이라면) 다른 그룹으로 여러 번 호출할 수 있어요.

Gemfile이 다음과 같다고 가정할게요.

gem 'first_gem', '= 1.0'
group :test do
  gem 'second_gem', '= 1.0'
end

코드는 다음과 같이 동작해요.

Bundler.setup # allow all groups
Bundler.require(:default) # requires only first_gem
# ...later
Bundler.require(:test)   # requires second_gem

# File lib/bundler.rb, line 211
def require(*groups)
  setup(*groups).require(*groups)
end

reset!()

Bundler 상태(설정·루트·rubygems 등)를 모두 초기 상태로 재설정해요.

reset_paths!()

경로 관련 상태를 재설정해요.

reset_rubygems!()

Rubygems 관련 상태를 재설정해요.

reset_settings_and_root!()

설정과 루트를 재설정해요.

rm_rf(path)

경로를 재귀적으로 삭제해요.

root()

Bundler가 실행 중인 프로젝트의 루트 경로를 반환해요.

ruby_scope()

Ruby 스코프 문자열을 반환해요.

safe_load_marshal(data)

marshal 데이터를 안전하게 로드해요.

self_manager()

Bundler::SelfManager 인스턴스를 반환해요 (자기 관리 기능).

settings()

Bundler::Settings 인스턴스를 반환해요 (설정 해시 접근).

setup(*groups)

Bundler 런타임을 켜요. Bundler.setup 호출 후에는 Gemfile에 있거나 Ruby 표준 라이브러리인 gem만 로드·require할 수 있어요. Gemfile에 버전이 지정되어 있다면 그 버전만 로드돼요.

Gemfile이 다음과 같다고 가정할게요.

gem 'first_gem', '= 1.0'
group :test do
  gem 'second_gem', '= 1.0'
end

Bundler.setup을 사용하는 코드는 다음과 같이 동작해요.

require 'third_gem' # allowed, required from global gems
require 'first_gem' # allowed, loads the last installed version
Bundler.setup
require 'fourth_gem' # fails with LoadError
require 'second_gem' # loads exactly version 1.0

Bundler.setup은 한 번만 호출할 수 있고, 이후 호출은 no-op이에요. groups 목록이 주어지면 지정된 그룹의 gem만 허용돼요(그룹 밖에 지정된 gem은 특별한 :default 그룹에 속해요). Gemfile의 모든 gem(또는 일부 그룹만)을 require하려면 Bundler.require를 보세요.

# File lib/bundler.rb, line 154
def setup(*groups)
  # Return if all groups are already loaded
  return @setup if defined?(@setup) && @setup

  definition.validate_runtime!

  SharedHelpers.print_major_deprecations!

  if groups.empty?
    # Load all groups, but only once
    @setup = load.setup
  else
    load.setup(*groups)
  end
end

specs_path()

gem 스펙 경로를 반환해요.

system_bindir()

시스템 바이너리 디렉터리를 반환해요.

tmp(name = Process.pid.to_s)

Bundler 임시 디렉터리 아래에 이름이 붙은 경로를 반환해요.

ui()

Bundler::UI 객체를 반환해요.

ui=(ui)

Bundler::UI 객체를 설정해요.

unbundle_env!()

환경에서 Bundler 변수를 제거해요.

unbundled_env()

Bundler 변수가 제거된 환경 해시를 반환해요.

unbundled_exec(*args)

Bundler가 없는 환경에서 명령을 exec 해요.

unbundled_system(*args)

Bundler가 없는 환경에서 시스템 명령을 실행해요.

use_system_gems?()

시스템 gem을 사용하는지 반환해요.

user_bundle_path(dir = "home")

사용자 번들 경로를 반환해요.

user_cache()

사용자 캐시 경로를 반환해요.

user_home()

사용자 홈 경로를 반환해요.

which(executable)

실행 파일의 경로를 PATH에서 찾아 반환해요.

with_clean_env() { || ... }

Bundler가 없는 깨끗한 환경에서 블록을 실행해요.

with_original_env() { || ... }

원래 환경에서 블록을 실행해요.

with_unbundled_env() { || ... }

Bundler 변수가 제거된 환경에서 블록을 실행해요.

Private Class Methods

configure_gem_home(path)

gem home을 구성해요.

configure_gem_path()

gem path를 구성해요.

eval_gemspec(path, contents)

gemspec 내용을 평가해 반환해요.

eval_yaml_gemspec(path, contents)

YAML gemspec 내용을 평가해 반환해요.

load_marshal(data, marshal_proc: nil)

marshal 데이터를 로드해요.

tmp_home_path()

임시 홈 경로를 반환해요.

unbundle_env(env)

지정한 환경 해시에서 Bundler 변수를 제거해 반환해요.

with_env(env) { || ... }

지정한 환경 해시로 임시 교체한 뒤 블록을 실행해요.

더 알아보기

• require 'bundler/setup' — 프로젝트 의존성만 사용할 수 있는 환경을 자동 설정.
• Bundler::Settings, Bundler::Definition, Bundler::Environment 등 내부 클래스.