diff options
Diffstat (limited to 'docs/en/developers/01_First_steps.md')
| -rw-r--r-- | docs/en/developers/01_First_steps.md | 120 |
1 files changed, 78 insertions, 42 deletions
diff --git a/docs/en/developers/01_First_steps.md b/docs/en/developers/01_First_steps.md index adca4495b..28c249be4 100644 --- a/docs/en/developers/01_First_steps.md +++ b/docs/en/developers/01_First_steps.md @@ -1,6 +1,59 @@ -# Environment configuration +# Environment configuration (Docker) -**TODO** +FreshRSS is built with PHP and uses a homemade framework, Minz. The dependencies are directly included in the source code, so you don't need Composer. + +There are various ways to configure your development environment. The easiest and most supported method is based on Docker, which is the solution documented below. If you already have a working PHP environment, you probably don't need it. + +We assume here that you use a GNU/Linux distribution, capable of running Docker. Otherwise, you'll have to adapt the commands accordingly. + +The commands that follow have to be executed in a console. They start by `$` when commands need to be executed as normal user, and by `#` when they need to be executed as root user. You don't have to type these characters. A path may be indicated before these characters to help you identify where they need to be executed. For instance, `app$ echo 'Hello World'` indicates that you have to execute `echo` command in the `app/` directory. + +First, you need to install [Docker](https://docs.docker.com/install/linux/docker-ce/ubuntu/). + +Once you're done, clone the repository with: + +```console +$ git clone https://github.com/FreshRSS/FreshRSS.git +$ cd FreshRSS +``` + +Note that, if you want to contribute, you have to fork the repository first and clone your fork instead of the "root" one. Adapt the commands in consequence. + +Then, the only command you need to know is the following: + +```console +$ make start +``` + +This might take some time while Docker downloads the image. If your user isn't in the `docker` group, you'll need to prepend the command with `sudo`. + +**You can now access FreshRSS at [http://localhost:8080](http://localhost:8080).** Just follow the install process and select the SQLite database. + +You can stop the containers by typing <kbd>Control</kbd> + <kbd>c</kbd> or with the following command, in another terminal: + +```console +$ make stop +``` + +If you're interested in the configuration, the `make` commands are defined in the [`Makefile`](/Makefile). + +If you need to use a different tag image (default is `dev-alpine`), you can set the `TAG` environment variable: + +```console +$ TAG=dev-arm make start +``` + +You can find the full list of available tags [on the Docker hub](https://hub.docker.com/r/freshrss/freshrss/tags). + +You might want to rebuild the Docker image locally. You can do it with: + +```console +$ make build +$ # or +$ TAG=dev-arm make build +``` + +The `TAG` variable can be anything (e.g. `dev-local`). You can target a specific architecture by adding `-alpine` or `-arm` at the end of the tag (e.g. `dev-local-arm`). # Project architecture @@ -8,7 +61,7 @@ # Extensions -If you want to create your own FreshRSS extension, take a look at the [extension documentation](03_Backend/05_Extensions.md). +If you want to create your own FreshRSS extension, take a look at the [extension documentation](03_Backend/05_Extensions.md). # Coding style @@ -57,7 +110,7 @@ There is a space before and after every operator. ```php if ($a == 10) { - // do something + // do something } echo $a ? 1 : 0; @@ -69,11 +122,11 @@ There is no spaces in the brackets. There is no space before the opening bracket ```php if ($a == 10) { - // do something + // do something } if ((int)$a == 10) { - // do something + // do something } ``` @@ -84,16 +137,16 @@ It happens most of the time in Javascript files. When there is chained functions ```javascript // First instruction shortcut.add(shortcuts.mark_read, function () { - //... - }, { - 'disable_in_input': true - }); + //... + }, { + 'disable_in_input': true + }); // Second instruction shortcut.add("shift+" + shortcuts.mark_read, function () { - //... - }, { - 'disable_in_input': true - }); + //... + }, { + 'disable_in_input': true + }); ``` ## Line length @@ -105,7 +158,7 @@ With functions, parameters can be declared on different lines. ```php function my_function($param_1, $param_2, $param_3, $param_4) { - // do something + // do something } ``` @@ -120,7 +173,7 @@ They must follow the "snake case" convention. ```php // a function function function_name() { - // do something + // do something } // a variable $variable_name; @@ -132,7 +185,7 @@ They must follow the "lower camel case" convention. ```php private function methodName() { - // do something + // do something } ``` @@ -148,26 +201,9 @@ abstract class ClassName {} Files must be encoded with UTF-8 character set. -## PHP 5.3 compatibility - -Do not get an array item directly from a function or a method. Use a variable. - -```php -// code with PHP 5.3 compatibility -$my_variable = function_returning_an_array(); -echo $my_variable[0]; -// code without PHP 5.3 compatibility -echo function_returning_an_array()[0]; -``` - -Do not use short array declaration. +## PHP compatibility -```php -// code with PHP 5.3 compatibility -$variable = array(); -// code without PHP 5.3 compatibility -$variable = []; -``` +Ensure that your code is working with a PHP version as old as what FreshRSS officially supports. ## Miscellaneous @@ -177,7 +213,7 @@ They must be at the end of the line if a condition runs on more than one line. ```php if ($a == 10 || $a == 20) { - // do something + // do something } ``` @@ -190,9 +226,9 @@ If the file contains only PHP code, the PHP closing tag must be omitted. If an array declaration runs on more than one line, each element must be followed by a comma even the last one. ```php -$variable = array( - "value 1", - "value 2", - "value 3", -); +$variable = [ + "value 1", + "value 2", + "value 3", +]; ``` |