Introducing Gem. Part two

Good day!

Instead of introducing

I finally found some time to continue my narrative of the various wonders in Ruby. As you remember, in the last part we got acquainted with the basics of writing our gem. We learned what the minimum set of files must be in order to collect it. We also learned how we can publish our creation in RubyGems. On the same day (after writing the first part), a surge of gems called hello-world suddenly appeared in RubyGems . And I found quite a lot of variations thereof. Some did not even bother to change the line where the author of the gem is indicated.

g.author = "krovatti"

Some even asked the gem the following version values:

g.version = "666"
g.version = "111"
g.version = "911"

In general, there were quite a few other variations that, as an author, of course, could not but rejoice me.

What awaits us today

In today's part, I would like to present you an overview of the properties available to us in the specification file. The knowledge of these very properties is, in my opinion, MUST HAVE .
Since we already know how to build gems, we will move on to the theory itself.

Where do we start

To start the enumeration, I think, is in the following order:

• first we’ll look at the necessary properties,
• and then consider the optional ones, i.e. optional properties.

So, let's begin.

date

Type: Time.
Default value: Time.now
Description: Date / time when the gem was created.
Example:

g.date = File.utime('VERSION')

Note: usually this field is not filled by programmers, because it already has a default value.

name

Type: String.
Default value: none.
Description: The name of our gem.
Example:

g.name = 'woohaha'

Note: you cannot write the version number of our gem in the name, as There is a separate field for this.

platform

Type: String.
Default value: Gem :: Platform :: Ruby
Description: The platform for which, in fact, we wrote our gem.
Example:

g.platform = Gem::Platform::Win32

Note: this property is worth filling only if your gem has an extension designed only for a specific platform. For example, we wrote a Win API wrapper.

require_paths

Type: Array.
Default value: ["lib"]
Description: Listing, which indicates the mandatory presence of a folder with our .rb or README files.
Example:

# если все файлы расположены в корневом каталоге
g.require_paths = '.'
# или, например, у нас есть папки 'lib и 'ext'
g.require_paths << 'ext'

Note: this property should not be used only in the case of HelloWorlds, but in the rest it is undoubtedly worth it, because sometimes it’s still convenient to have horses in their stables, and not to keep all in one.

summary

Type: String.
Default value: none.
Description: A brief description of our gem.
Example:

g.summary = 'I love Ruby and this extension was created specially for its beauty'

Note: this property is often confused with the description property , which is a less important property.

And the last required property for today. and for life

version

Type: String.
Default value: none.
Description: version of our gem.
Example:

g.version = '1.0.5'

Note: the values ​​represented by the Gem :: Version class can also be a valid value , but basically no one uses it. Remember that a string should contain only numeric values, not text.

That's all. We dealt with the required properties. Now, you can safely substitute your names, version numbers and more, and not publish them under my name. Just kidding, I certainly do not mind.
Are you tired? Strong? You can have a cup of coffee, and then return to us for a light.

So, let's continue

In addition to the required properties that you must apply, do not forget about the optional ones. Well, let's get started.

author or authors

Type: String or Array, in case there are several authors.
Default value: none.
Description: indicates the name or nickname of the author of the gem , or of the creator of the universe of the library contained in the gem.
Example:

# если автор один
g.author = 'Mike Vazovski'
# или же их несколько
g.authors = ['Mike Vazovski', 'Vladimir Putin']

Note: no comment.

autorequire

No, we won’t be distracted by it, because it was banned a long time ago as unnecessary. And let's move on.

bindir

Type: String.
Default value: “bin”
Description: A folder containing the files of an executable file, i.e. applications, if any.
Example:

g.bindir = 'bin'

Note: “application” means any file that can be executed through the command line.

default_executable

Type: String.
Default value: none . Has . As in the column "marital status" everything is complicated . Not really. Read the note.
Description: A folder containing an application that can be launched from the gem.
Example:

g.default_executable = 'bin/debin'

Note: if only one directory is specified in executables , then it will be the value for default_executable . This value is worth touching if you have two or more executable files.

dependencies

Type: Array.
The default value is [], i.e. nothing is required.
Description: Listing gems required for our work.
Example:

g.add_dependencies 'sinatra'

Note: first, the repository in which the already installed gems live will be checked. If we find what we need, then nothing terrible will happen, nor will it find it. In this case, the gems that are missing for work will be downloaded from the RubyGems repository.

development_dependencies

The property is similar to the previous one.

description

In fact, this property is not recommended. Instead, use summary

email

Type: String or Array.
Default value: none.
Description: e-mail for feedback from the author / authors.
Example:

# если автор один
g.email = 'krovatti@gmail.com'
# если авторов несколько
g.email = ['blablabla@yahoo.eu','krovatti@gmail.com']

Note: this was also a hint for read-only accounts, which, in the circumstances, often simply can not contact the author of the topic for any questions that interest them.

executables

We already talked about this property in default_executable . Nothing more to say about him.

extensions

Type: Array.
Default value: none.
Description: Directories containing extension files.
Example:

g.extensions << 'ext/rmagic/wtf.rb'

Note: these files will be launched when the gem is installed and the extensions are compiled.

extra_rdoc_files

Type: Array.
Default value: none.
Description: Listing of additional files that will be used when generating the RDoc documentation.
Example:

g.extra_rdoc_files = ['README', 'doc/user-guide.txt']

Note: no comment.

files

Type: Array.
Default value: none.
Description: Listing the files contained in the gem.
Example:

g.files = Dir['lib/**/*.rb]

Note: there is also nothing special to comment on.

has_rdoc

Type: Boolean.
Default value: false
Description: Indicates whether documentation exists for this RDoc gem.
Example:

g.has_rdoc = true

Note: a property eating away a certain number of bytes in your file.

homepage

Type: String.
Default value: microsoft.com, yeah it doesn’t.
Description: the site address of this gem.
Example:

g.homepage = 'http://github.com/ln/xmpp4r'

Note: also no comment.

license or licenses

Type: String or Array.
Default value: none.
Description: The license / licenses under which gems were published.
Example:

g.license = 'MIT' # если одна лицензия
g.licenses = ['MIT', 'GPL-2'] # если двойная лицензия, например

Note: each license name must be 64 characters or less.

rdoc_options

Type: Array.
Default value: []
Description: specifies the formatting of the RDoc documentation.
Example:

g.rdoc_options << '--title' << 'Rake -- Ruby Make' << '--main' << 'README' << --line-numbers'

Note: try and make sure it works.

required_ruby_version

Type: Gem :: Version :: Requirement.
Default value: > 0.0.0
Description: The version of Ruby needed to work with our gem.
Example:

g.required_ruby_version = '>= 1.8.1'

Note: a very useful feature that will lead to fewer errors when trying to use a gem. Take the situation with the same XMPP4R, which does not work with 1.9.0, or start up in the mood.

requirements

We will not consider this property as unnecessary, because it carries only textual information for the user.

rubyforge_project

Type: String.
Default value: none.
Description: The name of the project on RubyForge.
Example:

g.rubyforge_project = 'yahoo-eu'

Note: if you do not have a RubyForge project, do not touch this property as unnecessary.

And, lo and behold (!!!) the last property.

test_files

Type: String or Array.
Default value: '' or []
Description: The directory / directories that contain your unit tests, if any.
Example:

g.test_files = 'tests/wtf.rb' # 1
g.test_files = ['tests/wtf.rb',tests/wtf2.rb']

That's all

This completes the second part of our introduction to gem. Today we learned about all kinds of properties used to correctly configure the gem. I would like to congratulate those who reached the end of this topic with healthy eyes. But, alas, there will be no boobs!

See you soon!

Oh yes, I almost forgot. You can also be guided by this guide when consolidating what you have learned.