New Developers' Guide

CFAN - New contributor guidelines

CFAN - fork of CKAN

CFAN is a fork of CKAN. The most important changes are:

• netkan and meta repository has been removed
• netfan aggregates mod sources (factoriomods.com, github and few manual downloads/packs) and creates repository.tar.gz that clients download
• CFAN compiles only on Mono >=4.2, since it uses string interpolation using $ sign with ternary operator inside. It could probably be compiled on lower versions with some work, but there's no need for this.
• schema has been dumbed down, since we don't have any additional data than what can be found in info.json (not much)
• mod installation handles only single zip files
• additional dev tools were note adapted for CFAN, apart from bin/build and netfan

Other than that, this page should be useful.

About this document

This document aims to explain the inner workings of CFAN as well as describe the currently agreed upon workflow. Hopefully, this will reduce friction for new contributors entering CFAN development.

As with anything CFAN, this document is always open to corrections and improvements. Please note that any contribution must follow the Contribution guidelines and the Code of Conduct.

Due to CFAN being actively developed this document may be incomplet or inkorrekt, some details may change or may have already changed. Hopefully the program structure remains relatively the same (or it'd be reasonable to update this).

All code examples are in pseudo- C#. All typenames look like SomeClassType. This is some code:

void foo() { return 1; }

foo(1);

The CFAN project

In its essence, CFAN consists of a core library module ("core"), a command-line client ("the command-line") and a GUI client ("the GUI") - collectively referred to as "CFAN" and a large number of supporting tools such as parsers, validators and bots ("CFAN Tools", "the tools" or "the toolset").

While CFAN itself is written exclusively in C# .NET, the toolset sports a variety of programming languages such as Perl, bash and others. Contributions to CFAN are expected to be in C#, use .NET 4.5 and be compatible with both Mono (Win32, Linux, MacOSX) and Visual Studio (Win32) environments. There is no such limitation present when contributing to the tools, they can be in any language and use any platform as long as it is FOSS and is available on all of our development targets - modern Linux- based and Windows operating systems.

Glossary

• Client - an end-user software package that enables the user to manage his or her installed mods by using metadata provided by a CFAN repository

• Repository - an online service which enables clients to fetch the latest available mod metadata and mod authors to upload new metadata

• Module - A modification or enhancement to Factorio, provided by mod authors to users under a certain license. A module is a collection of files, their licensing and the metadata related to those files. Uniquely identified by a string called identifier

• Metadata - a JSON- encoded string that represents all the metadata related to a particular module without the contents of the module itself. It describes the mod itself (e.g. version, author, download url, homepage etc.) as well as the steps necessary to perform a complete installation. The metadata also contains information about the relationships between mods such as dependencies and recommendations. Note that the metadata does not usually fall under the same license as the mod contents.

• Mono - the FOSS Mono project is a complete .NET- compatible platform available for all modern desktop operating systems. Used in lieu of Microsoft's .NET where the latter is not available (more or less everything but Windows).

CFAN Core

The core of CFAN contains all the code necessary to facilitate basic package management operations such as communicating with a CFAN repository and installing modules.

You can find all relevant code for this section in master/CFAN/Core.

Here's the important stuff (in no particular order):

CfanModule (CfanModule.cs)

• Available CfanModules are generated at run-time by JSON- parsing repository- obtained .cfan metadata files and are located in the Registry.
• Contains accessors for all schema fields, for example:

CfanModule mod = ...;
Console.WriteLine(mod.download);

will print the download URL for a mod. Note that optional fields in the schema can result in null values, so remember to check!

• Modules are uniquely identified by their string identifier field, two different mods cannot have the same identifier (this is enforced at repository level)

Registry (Registry.cs)

• Represents a database of modules
• The two important fields are two dictionaries - available_modules and installed_modules. Both are indexed by a module identifier.
• available_modules is a dictionary mapping a string module identifier to an AvailableModule (AvailableModule.cs) instance. This is the list of all modules currently available in the repository. AvailableModule is a helper class that tracks module versions. This allows multiple versions of a single mod to co-exist in the repository. A call to AvailableModule.Latest(FactorioVersion ksp_version = null, ModDependency relationship = null) will produce a CfanModule compatible with the given Factorio version (or throw if no such version exists)
• installed_modules tracks all CFAN installed modules. It uses the InstalledModule(InstalledModule.cs) class which contains a list of installed files and a CfanModule instance.

RegistryManager (RegistryManager.cs)

• Singleton, use RegistryManager.Instance()
• Holds the current registry and provides methods for serialization
• In most cases you will need the registry field which is the current Registry

ModuleInstaller (ModuleInstaller.cs)

• Singleton, use ModuleInstaller.Instance
• Contains all the logic for installing, updating and uninstalling modules
• Important public functions are IsCached, InstallList, Uninstall
• InstallList is what the clients call to install mods. It resolves dependencies according to RelationshipResolverOptions, downloads the data and performs the necessary file operations.
• Uninstall will automatically uninstall mods that depend on whatever you're uninstalling unless you explicitly tell it not to.

Factorio

Net

RelationshipResolver

RelationshipResolverOptions

Repo

User (User.cs)

• The User class allows interaction with the User from core code
• Works in both the command-line and GUI clients
• WriteLine displays a message to the user
• YesNo displays a message and a Yes/No prompt
• Error displays an error
• Use sparingly, popping up 20 dialogs at once in the GUI is not fun for the user :(

Logging

We use log4net for logging.

Command-line client

The command-line client resides in CmdLine/CmdMain.cs. This is the place to look if you wish to know how a particular feature works or if you're just starting to read the code.

GUI client

The GUI client is sadly much more complicated than the command-line one, mostly because 90% of it is interface code with WindowsForms and the window designs themselves. The GUI is done in Visual Studio and although there are other WindowsForms editors, they have not been tested with CFAN (tell us if they work :P).

CFAN Tools

Setting up your development environment

See also the wiki on Build Environment.

Linux- based operating systems

You will need at least MonoDevelop and Mono to be able to open and build the CKAN.sln file. You can use xbuild that comes with Mono for command-line builds. To use it, run xbuild in the directory containing CFAN.sln. MonoDevelop aims to be a full C#- capable IDE similarly to Visual Studio as comes with an editor, compiler and debugger.

Windows

You most likely want to use Visual Studio. Although proprietary, the Express version is fully capable (same compiler as the other versions) and comes at zero cost. As an alternative, you can also use MonoDevelop on Windows.

First thing you will have to do is fork CFAN's master branch.

Communication with other contributors

You can post to factorio forum post.