UppHub
Table of contents
1. User perspective
2. Requirements
2.1 Git
2.1.1 Windows
2.1.2 POSIX
2.1.3 macOS
3. Package developer perspective
3.1 Overview
3.2 Publishing package
4. Maintainer information
5. Global registry
1. User perspective
UppHub is a system intended to catalogue and install independently developed U++ packages over the network.
UppHub is accessible from TheIDE menu Setup/UppHub or from the package selection.
UppHub modules are basically U++ nests (means they can contain multiple packages, including examples and testing code) which are automatically installed by cloning Git repository into common directory. U++ project system then automatically adds all nests from this folder at the end of assembly which makes all installed UppHub packages available for all projects.
Default location of this common folder is in TheIDE configuration folder, but this can be changed on per assembly setup:
or even globally from TheIDE Setup/Settings... menu:
2. Requirements
2.1 Git
Each UppHub package is represented by separate Git repository. It means that UppHub requires git availability in the environment path.
2.1.1 Windows
On Windows platform we bundle TheIDE distribution with mini git and no extra actions are needed by the user.
2.1.2 POSIX
On POSIX platforms user must have git installed and available through environment. It is available by default after git installation with various package managers such as apt. By default git should be installed with U++ installation script that user must lunch
2.1.2 macOS
On macOS platform user must have git installed and available through environment. Git could be installed with brew package manager.
3. Package developer perspective
3.1 Overview
U++ modules are developed as git repositories representing U++ nests. The name of module and of core packages that are intended to be used in other projects should have unique name (not that most often there will be one such package and its name will be the same as the name of module). Module nest can also contain some main-package: examples and testing packages. Following rules are suggested:
do not mix packages in single UppHub nest that are solving different problems (like mixing SysInfo with STEM4U)
try to make sure the package names that are to be used are unique (obvious reasons) - does not apply the name of examples, tests and other main packages that come with the module.
if you are adapting 3rd party code (or perhaps format), consider putting it to plugin (like plugin/md)
put examples into examples directory
put U++ style tests (those that can be be compiled / run automatically and fail with non-zero exit, e.g. with ASSERT) into autotest directory
put other tests to test
3.2 Publishing package
In order to publish the package to a wider audience you need to create git repository that is publicly available and created according to the instructions in the previous point. After that, you need to let us know that your package should be entered into the global registry. You could do it by creating appropriate thread in UppHub forum or by creating issue in this repository. Do not forget to describe what the package is supposed to do. This will help with verification. If everything will be alright, our maintainers will do the rest.
The process is very easy and even beginners shouldn't have problem with it.
We encourage all U++ users to create own packages and to share them with the community. Thanks to that we will grow as a framework and community.
4. Maintainer information
This information is only important for maintainers of UppHub and packages owners. Module nests are listed in json files that are accessible through http. JSON file specifies information about individual module lists, but can also reference other lists of modules:
{
"nests": [
{ "name": "Turtle",
"packages": [ "Turtle"],
"description": "Provides HTML5 web application with U++ plain GUI code",
"repository": "https://github.com/mirek-fidler/Turtle.git",
"status": "experimental",
"category": "networking",
"readme": "https://raw.githubusercontent.com/mirek-fidler/Turtle/master/README.md"
},
{ "url": "https://www.ultimatepp.org/forums/index.php?t=msg&goto=55566&#msg_55566"
}
],
"links": [
"https://www.ultimatepp.org/forums/index.php?t=msg&th=11264&start=0&"
]
}
nests array contains information about modules - its name, set of packages in the list intended to be used in projects, description, status (e.g. unstable, experimental, testing, stable..), category and the location of readme file. The repository contains the location of git https repository. Eventual tag or branch can be specified in branch. Alternatively, the entry can by defined with url which points to https location with the same content.
Additionally, the list can contain links to other lists.
5. Global registry
The global json file with all packages list is stored in this public repository. It is read by TheIDE by obtaining this file via network request. It is downloaded each time UppHub dialog is being opened.
|
