Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

The “bin” files RubyGems installs aren’t actually binary, improve naming #2372

Closed
bronzdoc opened this issue Jul 30, 2018 · 8 comments · Fixed by #2383
Closed

The “bin” files RubyGems installs aren’t actually binary, improve naming #2372

bronzdoc opened this issue Jul 30, 2018 · 8 comments · Fixed by #2383
Assignees

Comments

@bronzdoc
Copy link
Member

See discussion in #2361

@ghost
Copy link

ghost commented Jul 30, 2018

I'll try to list the different names used in RubyGems and where they are used
later, but in the mean time I just found another relevant discussion here:

@MSP-Greg
Copy link
Contributor

When I see bin/binary, I think compiled. When I see exe/exec/executable, somewhat the same thing, with the additional issue of windows users are used to compiled apps having an .exe file extension.

Maybe 'CLI files' or 'CLI scripts'? If a user isn't familiar with the term, Google 'CLI', and the first line is 'Command-line interface'. I would hope that would be clear to people...

@segiddins
Copy link
Member

We also call them binstubs in Bundler

@MSP-Greg
Copy link
Contributor

It's also messy because Windows needs a bat/cmd file to launch the *nix style script from Ruby, and I think those are called binstubs in RG.

Maybe we should call them 'TFIYBEF', short for 'The Files In Your Bin or Exe Folders'. Ok, been at a keyboard too long today...

@ghost
Copy link

ghost commented Aug 6, 2018

TL;DR:

  • I would only change --bindir option description;
  • I would remove reference to "stub" when it's about gem executable
    wrappers. I think of other things first ("test stub"…) and see it's
    used in Gem::Specification and Gem::StubSpecification. Referring
    to wrappers is less obvious for me with this term.

--bindir option in many commands

In my opinion the option name is correct and clear, this is the bin
directory, which is also the default value (bin) and referred as
such almost everywhere.
I think "bin files" in description would be acceptable, because we
refer to their parent directory in this case, but "binary files" or
"binaries" is not correct IMHO and could be confused with extensions.

Terminology used elsewhere

I'll quote part of the doc for Gem::Specification#executables and
Gem::Installer which I think are clear:

##
# Executables included in the gem.
#
# For example, the rake gem has rake as an executable. You don’t specify the
# full path (as in bin/rake); all application-style files are expected to be
# found in bindir.  These files must be executable Ruby files.  Files that
# use bash or other interpreters will not work.
#
# Executables included may only be ruby scripts, not scripts for other
# languages or compiled binaries.

# Gem::Installer does the work of putting files in all the right places on the
# filesystem including unpacking the gem into its gem dir, installing the
# gemspec in the specifications dir, storing the cached gem in the cache dir,
# and installing either wrappers or symlinks for executables.

So in a gem, we have executable Ruby scripts, and we install either
an executable "wrapper" (which is also a Ruby script) or a symlink.
Those are the terms I personally prefer.


Notes (far from complete, might contain errors)

executable and/or wrapper

Used in option flags, help, code, code documentation, error
messages.

  • executables in a gem specification.
  • UI:
    • gem install --[no-]wrappers --[no-]format-executable;
    • gem pristine --only-executables;
    • gem uninstall --[no-]executables --[no-]format-executable;
    • gem update --[no-]wrappers --[no-]format-executable;
    • setup.rb --[no-]format-executable;
    • "For gems with executables ruby installs a wrapper file into the
      executable directory by default.";
    • "Use bin wrappers for executables";
    • "Only restore executables";
    • "Executables and scripts will remain installed."
    • "Rewrite executables with a shebang";
    • "RubyGems installed the following executables:";
    • "can't find gem #{dep} with executable #{exec_name}";
    • "#{spec.name}'s executable \"#{filename}\" conflicts with ";
    • ask_yes_no "#{question}\nOverwrite the executable?";
  • code or code documentation:
    • "executable for gem";
    • "executable's path";
    • "gem executables".
    • Gem.bin_path(name, exec_name = nil, *requirements);
    • Gem.find_spec_for_exe;
    • Gem::Commands::SetupCommand (format_executable);
    • Gem::DependencyInstaller (format_executable);
    • Gem::Installer;
    • Gem::Specification.

There is too much code examples for "executable" or just "exe", I gave
up at some point.
In RubyGems code, I think "executable" alone may refer to the
wrapper, or occasionally to the interpreter (Ruby) specified in the
wrapper's shebang.

bin and/or binary

"bin" is mostly used to refer to a "gem's bin path".

"binary files" is mostly used for extensions, with a few exceptions.

"bin file" is sometimes used, but I understand it as "a file inside
the bin directory", not a "binary file").

When referring to a directory, it can be either the one in a gem,
either the one in the installation directory.

  • bindir in a gem specification.
  • UI:
    • gem install --bindir;
    • gem pristine --bindir;
    • gem uninstall --bindir;
    • gem update --bindir.
    • "Use bin wrappers for executables";
    • "Directory where binary files are located".
  • code or code documentation:
    • Gem.bin_path;
    • Gem.bindir;
    • Gem.default_bindir "The default directory for binaries";
    • Gem::DependencyInstaller (bin_dir);
    • Gem::Installer (bin_dir or bindir, #generate_bin,
      #generate_bin_script, #generate_bin_symlink, #extract_bin…).

stub / bin stub

"stub" is mostly used for "stubbed specification" which is unrelated
to executable wrappers/links if I understand correctly. Only a few
occurrences are about executables/wrappers/scripts.

  • UI:
    • gem pristine command description: "all bin stubs for the gem";
    • setup.rb --[no-]regenerate-binstubs "Regenerate gem binstubs".
  • code:
    • Gem::Installer#windows_stub_script.

@ghost
Copy link

ghost commented Aug 6, 2018

When I see bin/binary, I think compiled. When I see exe/exec/executable, somewhat the same thing, with the additional issue of windows users are used to compiled apps having an .exe file extension.

I'm not familiar with the Windows case, but from my point of view
"exe/exec/executable" does not imply "compiled". As an example my /bin,
/usr/bin, /usr/local/bin directories contain hundred of shell, perl,
python, ruby scripts.

Maybe 'CLI files' or 'CLI scripts'? If a user isn't familiar with the term, Google 'CLI', and the first line is 'Command-line interface'. I would hope that would be clear to people...

I like "scripts" because it's more accurate than "executables". However I have
a little objection about "CLI", because not all scripts will implement one,
some will have a GUI instead, or others could have both CLI and GUI.

@bronzdoc
Copy link
Member Author

bronzdoc commented Aug 9, 2018

I would only change --bindir option description

so the description would be changed from:

Directory where binary files are 'located'

to:

Directory where executables  are 'located'

Agree? @segiddins @tjouan @MSP-Greg

@ghost
Copy link

ghost commented Aug 13, 2018 via email

bundlerbot added a commit that referenced this issue Aug 23, 2018
…by-swandale

Improve bindir flag description

# Description:
closes #2372

______________
I will abide by the [code of conduct](https://github.com/rubygems/rubygems/blob/master/CODE_OF_CONDUCT.md).
hsbt pushed a commit that referenced this issue Oct 10, 2018
…by-swandale

Improve bindir flag description

closes #2372

______________
I will abide by the [code of conduct](https://github.com/rubygems/rubygems/blob/master/CODE_OF_CONDUCT.md).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants