FAQ

How to install hell?

It's simple. You just need nodejs and npm. You can install it this way:

npm install -g rili-hell

However to use it you need to have installed git, cmake and any supported by cmake build system generator.

Can I use private git repositories as my project dependencies?

Yes, no problem. You only need to have access rights to these repositories.

Does Hell support http, git, ssh, local file system repositories?

Yes, it support as much protocols as your git client support. Hell don't have its own git implementation - it only run git executable with some arguments incantation and analyze git command stdout and stderr to do own stuff.

Which cmake versions are supported?

Hell don't have constrains about cmake version. Only your project dependencies are important in this matter, however cmake have very good backward-compatibility, so probably you don't need to care about it too much.

I want to use hell to install my project dependencies - how to do so?

  1. First of all check if project which you want use as dependency support hell. If it support you can go directly to point 6.
  2. Check if project which you want to use have proxy repo in hell-gates In this gitlab group you can find special kind of repos created for projects which not support hell or even cmake or are not hosted on git by maintainers. These repos provide cmake files and hell config files which allow to correctly install proxied projects by hell. For example you can find there gtest, boost, clang or llvm. If you found interesting proxy repo in hell-gates you can go directly to point 6.
  3. Ask maintainer of project you are interested in if he or she could add support of hell in project. If this is possible and you have enough time for that you can go to point 1.
  4. Create Issue on hell project with request to add project you want to use to hell-gates - there is high possibility it can be done fast. If you can wait and your request is accepted you can go to point 2.
  5. Ok. So you are here - it's time to to show you how to create your own proxy repo like these in hell-gates - go to section I want to allow hell users to work with my project - how to do so?
  6. So you know that there is existing source repo which can be used with hell, there are git tags which points interesting for you versions - you are prepared to create your first hell configuration file.

Probably best way to introduce you into this task will be by simple example:

{
  "=":[
    {
      "source":"https://gitlab.com/group1/project1.git",
      "version":">1.2.3 <3.4.5",
      "required":["="]
    }
  ],
  "WITH_FEATURE_X=ON":[
    {
      "source":"https://gitlab.com/group1/project2.git",
      "version":"1.0.3",
      "required":["=", "SOMETHING=ON", "SOMETHING_ELSE=OFF"]
    }
  ],
  "WITH_FEATURE_X=OFF":[],
  "WITH_FEATURE_Y=ON":[
    {
      "source":"https://gitlab.com/group2/project1.git",
      "version":"5.x",
      "required":["=", "MAGIC_TYPE=DARK"]
    }
  ],
  "WITH_FEATURE_Y=OFF":[],
}

This is example of .hell.json file. You need to create similar for your project - it should be placed in root directory of your project repository. Keys of root dict in this json config file(=, WITH_FEATURE_X=ON, WITH_FEATURE_X=OFF, WITH_FEATURE_Y=ON and WITH_FEATURE_Y=OFF) are known in hell as targets. Some of targets are exclusive - for example you cannot use both WITH_FEATURE_Y=ON and WITH_FEATURE_Y=OFF - target have 2 parts - name and value (in case of WITH_FEATURE_Y=ON name is WITH_FEATURE_Y and value is ON). All hell targets contain at least one = character. Target name must be valid cmake variable identifier and value any kind of string. Target = is special and is used as default one. Targets are very close related to cmake - hell will pass them into projects as they are so cmake will be able to detect options you want.

In case of our example config, we assume that, example project cmake support -D options: -DWITH_FEATURE_X=ON, -DWITH_FEATURE_X=OFF, -DWITH_FEATURE_Y=ON, -DWITH_FEATURE_Y=OFF. You should expose all user configurable options in your hell config as targets.

Sometimes when you enable some kind of feature in your project, you need additional dependencies. You can describe them as target array elements. In example config if someone will select "WITH_FEATURE_Y=ON" target, then we have dependency:

{
  "source":"https://gitlab.com/group2/project1.git",
  "version":"5.x",
  "required":["=", "MAGIC_TYPE=DARK"]
}

In this notation source entry is git repository url, where dependency is stored. version field describe which semver range of versions are acceptable for us (in given example hell will accept everything with major version = 5). required field is array which contain targets which we want from our dependency (so in this case default(=) + MAGIC_TYPE=DARK). Based on required field from our dependency hell can recursively go deeper and deeper in our dependency tree to find solution for us - of course in meantime it need to care about versions and targets conflicts and try resolve dependencies in another way when current is incorrect.

When you finally have prepared .hell.json for your projects you can try if it is valid using:

hell --verbose

This command will show you what hell found in your project or show error messages in case when your config file is not valid. If it's valid you can try install your project dependencies this way:

hell --install -r <some_target> -r <some_other_target> -i <some_cmake_build_option> -i <some_other_cmake_build_option>

This command will resolve your dependencies, build and install them into .hell directory.

I want to allow hell users to work with my project - how to do so?

Note:

Check if you understand .hell.json file structure - it's not hard but very important.

If you know hell config structure, you know how hell resolve project dependencies and how to create your own.

Additional hints regarding your .hell.json:

Cmake config files requirements which you need fulfill to allow hell to use your project as dependency:

Cmake install tree hints:

When you have prepared both .hell.json and install tree in cmake, you can commit changes into git repository and create first git tag. Remember that hell will care only about tags which are valid semantic versions - other are not interesting for hell. You can have without any problems tags in other form or semver tags but without .hell.json - hell will just filter them out.

What about hell command line options?

All of them with description you can find using:

hell --help

most important are:

What are hell-gates?

Hell gates are projects inside gitlab rilis/hell/gates group which provide proxy repositories with support to hell for well known and widely used libraries which do not support hell natively. These "proxy projects" are mostly not maintained by authors of libraries, but allow to install these libraries using hell.

If you know how to provide hell support for library which not natively support hell or even cmake, please let us know - We will create project inside hell-gates in which you will be able to provide / and maintain needed .hell.json and cmake files. This way most used libraries will be covered by hell without acceptance/additional work from given library maintainers/authors side and without introducing too much mess.

Can I use branch name as version?

Yes. You can use branch or tag name as version, however in this way hell will be not able to compare it to others using semver. Because of that we strongly suggest to not do that, however in some situations it's very convinient, so hell support it.

How to find hell packets?

Most convinient way to find hell packets is to use hell search engine in browser or directly in hell CLI using search command like:

hell --search openssl tls crypto

Search engine use weighted full text search algorithm, so will try find as much projects as possible which match to typed sequence of words at least partially.

Note:

New repositories are added to search index automatically after each succesfull hell install task completion by default for public avaliable repositories (you can disable this behaviour using --no-publish option).

Note:

If repository is frequently "added" to index it popularity metric variable incrase (popularity is used to sort results).

Note:

Data for search server is updated at least once per day for each known repository (project description, tags etc.) from github.com and gitlab.com - other hosts are not yet supported.

What for hell create .hell directory inside my project root directory?

.hell directory is some kind of internal hell workspace. In most cases it shouldn't be interesting for you. You can find inside:

Note:

If you care about hdd space and not plan to reinstall anything, then you can safely remove everything inside except install directory.

Note:

Inside source, build and repodb you can find subdirs which names are hashed based on corresponding repository url.

I want to contribute. Where is hell repository?

It's here: Hell repository. You are very welcome.