Module: Homebrew::Bundle::FlatpakInstaller Private

Defined in:
bundle/flatpak_installer.rb

This module is part of a private API. This module may only be used in the Homebrew/brew repository. Third parties should avoid using this module if possible, as it may be removed or changed without warning.

Class Method Summary collapse

Class Method Details

.add_remote!(flatpak, remote_name, url, verbose:) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Add a remote with appropriate flags

Parameters:

Returns:

  • (Boolean) 


158
159
160
161
162
163
164
165
166
167
 
# File 'bundle/flatpak_installer.rb', line 158

def self.add_remote!(flatpak, remote_name, url, verbose:)
  if url.end_with?(".flatpakrepo")
    Bundle.system flatpak, "remote-add", "--if-not-exists", "--system",
                  remote_name, url, verbose: verbose
  else
    # For bare repository URLs, add with --no-gpg-verify for user repos
    Bundle.system flatpak, "remote-add", "--if-not-exists", "--system",
                  "--no-gpg-verify", remote_name, url, verbose: verbose
  end
end

.ensure_named_remote_exists!(flatpak, remote_name, url, verbose:) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Ensure a named shared remote exists (Tier 3) Warn but don't change if URL differs (user explicitly named it)

Parameters:



130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'bundle/flatpak_installer.rb', line 130

def self.ensure_named_remote_exists!(flatpak, remote_name, url, verbose:)
  existing_url = get_remote_url(flatpak, remote_name)

  if existing_url && existing_url != url
    # Named remote with different URL - warn but don't change (user explicitly named it)
    puts "Warning: Remote '#{remote_name}' exists with different URL (#{existing_url}), using existing"
    return
  end

  return if existing_url # Already exists with correct URL

  puts "Adding named remote #{remote_name} from #{url}" if verbose
  add_remote!(flatpak, remote_name, url, verbose:)
end

.ensure_single_app_remote_exists!(flatpak, remote_name, url, verbose:) ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.

Ensure a single-app remote exists (Tier 2) Safe to replace if URL differs since it's isolated per-app

Parameters:



111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'bundle/flatpak_installer.rb', line 111

def self.ensure_single_app_remote_exists!(flatpak, remote_name, url, verbose:)
  existing_url = get_remote_url(flatpak, remote_name)

  if existing_url && existing_url != url
    # Single-app remote with different URL - safe to replace
    puts "Replacing single-app remote #{remote_name} (URL changed)" if verbose
    Bundle.system flatpak, "remote-delete", "--system", "--force", remote_name, verbose: verbose
    existing_url = nil
  end

  return if existing_url # Already exists with correct URL

  puts "Adding single-app remote #{remote_name} from #{url}" if verbose
  add_remote!(flatpak, remote_name, url, verbose:)
end

.generate_single_app_remote_name(app_id) ⇒ String

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Generate a single-app remote name (Tier 2) Pattern: -origin (matches Flatpak's native behavior for .flatpakref)

Parameters:

Returns:



104
105
106
 
# File 'bundle/flatpak_installer.rb', line 104

def self.generate_single_app_remote_name(app_id)
  "#{app_id}-origin"
end

.get_remote_url(flatpak, remote_name) ⇒ String?

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Get URL for an existing remote, or nil if not found

Parameters:

Returns:



147
148
149
150
151
152
153
154
 
# File 'bundle/flatpak_installer.rb', line 147

def self.get_remote_url(flatpak, remote_name)
  output = `#{flatpak} remote-list --system --columns=name,url 2>/dev/null`.chomp
  output.split("\n").each do |line|
    parts = line.split("\t")
    return parts[1] if parts[0] == remote_name
  end
  nil
end

.install!(name, preinstall: true, verbose: false, force: false, remote: "flathub", url: nil, **_options) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • name (String)
  • preinstall (Boolean) (defaults to: true)
  • verbose (Boolean) (defaults to: false)
  • force (Boolean) (defaults to: false)
  • remote (String) (defaults to: "flathub")
  • url (String, nil) (defaults to: nil)
  • _options (T.anything)

Returns:

  • (Boolean) 


44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'bundle/flatpak_installer.rb', line 44

def self.install!(name, preinstall: true, verbose: false, force: false, remote: "flathub", url: nil, **_options)
  return true unless Bundle.flatpak_installed?
  return true unless preinstall

  flatpak = Bundle.which_flatpak.to_s

  # 3-tier remote handling:
  # - Tier 1: no URL → use named remote (default: flathub)
  # - Tier 2: URL only → single-app remote (<app-id>-origin)
  # - Tier 3: URL + name → named shared remote

  if url.present?
    # Tier 3: Named remote with URL - create shared remote
    puts "Installing #{name} Flatpak from #{remote} (#{url}). It is not currently installed." if verbose
    ensure_named_remote_exists!(flatpak, remote, url, verbose:)
    actual_remote = remote
  elsif remote.start_with?("http://", "https://")
    if remote.end_with?(".flatpakref")
      # .flatpakref files - install directly (Flatpak handles single-app remote natively)
      puts "Installing #{name} Flatpak from #{remote}. It is not currently installed." if verbose
      return install_flatpakref!(flatpak, name, remote, verbose:)
    else
      # Tier 2: URL only - create single-app remote
      actual_remote = generate_single_app_remote_name(name)
      if verbose
        puts "Installing #{name} Flatpak from #{actual_remote} (#{remote}). It is not currently installed."
      end
      ensure_single_app_remote_exists!(flatpak, actual_remote, remote, verbose:)
    end
  else
    # Tier 1: Named remote (default: flathub)
    puts "Installing #{name} Flatpak from #{remote}. It is not currently installed." if verbose
    actual_remote = remote
  end

  # Install from the remote
  return false unless Bundle.system flatpak, "install", "-y", "--system", actual_remote, name,
                                    verbose: verbose

  installed_packages << { name:, remote: actual_remote }
  true
end

.install_flatpakref!(flatpak, name, url, verbose:) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Install from a .flatpakref file (Tier 2 variant - Flatpak handles single-app remote natively)

Parameters:

Returns:

  • (Boolean) 


89
90
91
92
93
94
95
96
97
98
99
 
# File 'bundle/flatpak_installer.rb', line 89

def self.install_flatpakref!(flatpak, name, url, verbose:)
  return false unless Bundle.system flatpak, "install", "-y", "--system", url,
                                    verbose: verbose

  # Get the actual remote name used by Flatpak
  output = `#{flatpak} list --app --columns=application,origin 2>/dev/null`.chomp
  installed = output.split("\n").find { |line| line.start_with?(name) }
  actual_remote = installed ? installed.split("\t")[1] : "#{name}-origin"
  installed_packages << { name:, remote: actual_remote }
  true
end

.installed_packages ⇒ Array<Hash{Symbol => String}>

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Returns:



181
182
183
184
185
186
187
 
# File 'bundle/flatpak_installer.rb', line 181

def self.installed_packages
  require "bundle/flatpak_dumper"
  @installed_packages ||= T.let(
    Homebrew::Bundle::FlatpakDumper.packages_with_remotes,
    T.nilable(T::Array[T::Hash[Symbol, String]]),
  )
end

.package_installed?(package, remote: nil) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

Returns:

  • (Boolean) 


170
171
172
173
174
175
176
177
178
 
# File 'bundle/flatpak_installer.rb', line 170

def self.package_installed?(package, remote: nil)
  if remote
    # Check if package is installed from the specified remote
    installed_packages.any? { |pkg| pkg[:name] == package && pkg[:remote] == remote }
  else
    # Just check if package is installed from any remote
    installed_packages.any? { |pkg| pkg[:name] == package }
  end
end

.preinstall!(name, verbose: false, remote: "flathub", url: nil, **_options) ⇒ Boolean

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

Parameters:

  • name (String)
  • verbose (Boolean) (defaults to: false)
  • remote (String) (defaults to: "flathub")
  • url (String, nil) (defaults to: nil)
  • _options (T.anything)

Returns:

  • (Boolean) 


21
22
23
24
25
26
27
28
29
30
31
 
# File 'bundle/flatpak_installer.rb', line 21

def self.preinstall!(name, verbose: false, remote: "flathub", url: nil, **_options)
  return false unless Bundle.flatpak_installed?

  # Check if package is installed at all (regardless of remote)
  if package_installed?(name)
    puts "Skipping install of #{name} Flatpak. It is already installed." if verbose
    return false
  end

  true
end

.reset! ⇒ void

This method is part of a private API. This method may only be used in the Homebrew/brew repository. Third parties should avoid using this method if possible, as it may be removed or changed without warning.

This method returns an undefined value.



8
9
10
 
# File 'bundle/flatpak_installer.rb', line 8

def self.reset!
  @installed_packages = nil
end