Generate an "include" directory with a README file when initializing a new project

HISTORY.rst

@@ -7,6 +7,8 @@ PlatformIO 3.0
 3.6.1 (2018-??-??)
 ~~~~~~~~~~~~~~~~~~
 
+* Generate an `include <http://docs.platformio.org/page/projectconf/section_platformio.html#include-dir>`__
+  directory with a README file when initializing a new project
 * Introduced `"Release" and "Debug" Build Configurations <http://docs.platformio.org/page/projectconf/build_configurations.html>`__
 * Build project in "Debug Mode" including debug information with a new
   ``debug`` target using `platformio run <https://docs.platformio.org/page/userguide/cmd_run.html>`__ command or `targets <http://docs.platformio.org/page/projectconf/section_env_general.html#targets>`__ option in ``platformio.ini``.

platformio/builder/tools/pioide.py

@@ -25,7 +25,7 @@ from platformio.managers.core import get_core_package_dir
 
 
 def _dump_includes(env):
-    includes = []
+    includes = [env.subst("$PROJECTINCLUDE_DIR"), env.subst("$PROJECTSRC_DIR")]
 
     for item in env.get("CPPPATH", []):
         includes.append(env.subst(item))

platformio/commands/init.py

@@ -73,21 +73,19 @@ def cli(
             click.secho(
                 "\nThe current working directory", fg="yellow", nl=False)
             click.secho(" %s " % project_dir, fg="cyan", nl=False)
-            click.secho(
+            click.secho("will be used for the project.", fg="yellow")
-                "will be used for the project.\n"
-                "You can specify another project directory via\n"
-                "`platformio init -d %PATH_TO_THE_PROJECT_DIR%` command.",
-                fg="yellow")
             click.echo("")
 
         click.echo("The next files/directories have been created in %s" %
                    click.style(project_dir, fg="cyan"))
-        click.echo("%s - Project Configuration File" % click.style(
+        click.echo("%s - Put your header files here" % click.style(
-            "platformio.ini", fg="cyan"))
+            "include", fg="cyan"))
-        click.echo(
-            "%s - Put your source files here" % click.style("src", fg="cyan"))
         click.echo("%s - Put here project specific (private) libraries" %
                    click.style("lib", fg="cyan"))
+        click.echo(
+            "%s - Put your source files here" % click.style("src", fg="cyan"))
+        click.echo("%s - Project Configuration File" % click.style(
+            "platformio.ini", fg="cyan"))
 
     init_base_project(project_dir)
 
@@ -102,16 +100,25 @@ def cli(
         pg = ProjectGenerator(project_dir, ide, env_name)
         pg.generate()
 
-    if not silent:
+    if silent:
+        return
+
+    project_inited_before = util.is_platformio_project(project_dir)
+    if ide:
         click.secho(
-            "\nProject has been successfully initialized!\nUseful commands:\n"
+            "\nProject has been successfully %s including configuration files "
-            "`platformio run` - process/build project from the current "
+            "for `%s` IDE." %
-            "directory\n"
+            ("updated" if project_inited_before else "initialized", ide),
-            "`platformio run --target upload` or `platformio run -t upload` "
+            fg="green")
-            "- upload firmware to embedded board\n"
+    else:
-            "`platformio run --target clean` - clean project (remove compiled "
+        click.secho(
-            "files)\n"
+            "\nProject has been successfully %s! Useful commands:\n"
-            "`platformio run --help` - additional information",
+            "`pio run` - process/build project from the current directory\n"
+            "`pio run --target upload` or `pio run -t upload` "
+            "- upload firmware to a target\n"
+            "`pio run --target clean` - clean project (remove compiled files)"
+            "\n`pio run --help` - additional information" %
+            ("updated" if project_inited_before else "initialized"),
             fg="green")
 
 
@@ -142,13 +149,63 @@ def init_base_project(project_dir):
         init_cvs_ignore(project_dir)
 
     with util.cd(project_dir):
-        lib_dir = util.get_projectlib_dir()
+        dir_to_readme = [
-        src_dir = util.get_projectsrc_dir()
+            (util.get_projectsrc_dir(), None),
-        for d in (src_dir, lib_dir):
+            (util.get_projectinclude_dir(), init_include_readme),
-            if not isdir(d):
+            (util.get_projectlib_dir(), init_lib_readme),
-                makedirs(d)
+        ]
+        for (path, cb) in dir_to_readme:
+            if isdir(path):
+                continue
+            makedirs(path)
+            if cb:
+                cb(path)
 
-    init_lib_readme(lib_dir)
+
+def init_include_readme(include_dir):
+    if isfile(join(include_dir, "readme.txt")):
+        return
+    with open(join(include_dir, "readme.txt"), "w") as f:
+        f.write("""
+This directory is intended for project header files.
+
+A header file is a file containing C declarations and macro definitions
+to be shared between several project source files. You request the use of a
+header file in your project source file (C, C++, etc) located in `src` folder
+by including it, with the C preprocessing directive `#include'.
+
+```src/main.c
+
+#include "header.h"
+
+int main (void)
+{
+ ...
+}
+```
+
+Including a header file produces the same results as copying the header file
+into each source file that needs it. Such copying would be time-consuming
+and error-prone. With a header file, the related declarations appear
+in only one place. If they need to be changed, they can be changed in one
+place, and programs that include the header file will automatically use the
+new version when next recompiled. The header file eliminates the labor of
+finding and changing all the copies as well as the risk that a failure to
+find one copy will result in inconsistencies within a program.
+
+In C, the usual convention is to give header files names that end with `.h'.
+It is most portable to use only letters, digits, dashes, and underscores in
+header file names, and at most one dot.
+
+Read more about using header files in official GCC documentation:
+
+* Include Syntax
+* Include Operation
+* Once-Only Headers
+* Computed Includes
+
+https://gcc.gnu.org/onlinedocs/cpp/Header-Files.html
+""")
 
 
 def init_lib_readme(lib_dir):
@@ -157,12 +214,12 @@ def init_lib_readme(lib_dir):
     with open(join(lib_dir, "readme.txt"), "w") as f:
         f.write("""
 This directory is intended for project specific (private) libraries.
-PlatformIO will compile them to static libraries and link them to executable files.
+PlatformIO will compile them to static libraries and link into executable file.
 
-The source code of each library should be placed in separate directories, like
+The source code of each library should be placed in a an own separate directory
-"lib/private_lib/[here are source files]".
+("lib/your_library_name/[here are source files]").
 
-For example, see the structure of the following two libraries `Foo` and `Bar`:
+For example, see a structure of the following two libraries `Foo` and `Bar`:
 
 |--lib
 |  |
@@ -184,15 +241,20 @@ For example, see the structure of the following two libraries `Foo` and `Bar`:
 |--src
    |- main.c
 
-Then in `src/main.c` you should use:
+and a contents of `src/main.c`:
-
+```
 #include <Foo.h>
 #include <Bar.h>
 
-// rest H/C/CPP code
+int main (void)
+{
+  ...
+}
 
-PlatformIO will find your libraries automatically, configure preprocessor's
+```
-include paths and build them.
+
+PlatformIO Library Dependency Finder will find automatically dependent
+libraries scanning project source files.
 
 More information about PlatformIO Library Dependency Finder
 - https://docs.platformio.org/page/librarymanager/ldf.html