1/// This struct describes in almost-C++ the json data structure as expected by the
2/// project plugin.
3/// The json file has to be named ".kateproject".
4struct
5{
6   /// name of the project
7   string name;
8
9   /// The "directory" is optional.
10   /// It is probably only useful for the kate-project-generator in cmake (>= 3.0.0).
11   /// If set, the directory given here is used as the base directory for the project.
12   /// Otherwise, the directory in which the project file is located as the base directory.
13   string directory;
14
15   /// The "files" struct describes which files belong to the project.
16   /// There are five miutually exclusive methods to do this.
17   struct files
18   {
19      /// "directory" is the files directory. If it is empty, the project base directory
20      /// will be used. If it is a relative path, it is appended to the project
21      /// base directory. Absolute paths work too.
22      string directory;
23
24      /// If "git" is set to "1", the list of files is retrieved by running git in the files directory.
25      bool git;
26
27      /// If "hg" is set to "1", the list of files is retrieved by running hg (mercurial) in the files directory.
28      bool hg;
29
30      /// If "svn" is set to "1", the list of files is retrieved by running svn (subversion) in the files directory.
31      bool svn;
32
33      /// "list" can be set to a list of files.
34      vector< string > list;
35
36      /// If nothing of the above has been set, "filters" can be set to a list of globbing expressions, which
37      /// will be executed in the files directory.
38      vector< string > filters;
39
40      /// If "recursive" is set to 1, the globbing expressions in filters are executed recursively in the directory tree.
41      bool recursive;
42   };
43
44   /// The "build" structure is optional.
45   /// If set, its contents are used by the build plugin in kate.
46   /// "targets", "default_target" and "clean_target" are supported starting with kate 4.13.
47   /// The "build", "clean" and "quick" fields are only used if "targets" is empty.
48   /// They servce for backward compatibility with the build plugin < 4.13, or they can
49   /// be used as a quicker way to set up projects with up to 3 targets.
50   struct build
51   {
52      /// The build directory
53      string directory;
54
55      /// "targets" contains a vector of targets (as in a makefile). Each target has a name
56      /// and a command. The commands are exeucted in the build directory.
57      vector< {string name, string build_cmd} > targets;
58
59      /// "default_target" must be set to one of the target names in "targets". This is the target
60      /// which will be built by the "Build default target" action of the build plugin.
61      string default_target;
62
63      /// "clean_target" must be set to one of the target names in "targets". This is the target
64      /// which will be built by the "Build clean target" action of the build plugin.
65      string clean_target;
66
67      /// Creates a target names "build" with the given command.
68      string build;
69
70      /// Creates a target names "clean" with the given command.
71      string clean;
72
73      /// Creates a target names "quick" with the given command.
74      string quick;
75
76   };
77
78   /// The "ctags" structure is optional.
79   /// If set, it may contain extra options for ctags command used to populate the auto completion popup in Kate.
80   struct ctags
81   {
82      /// If "enable" is set to "1", a ctags index file is generated.
83      /// If not present, generation of index depends on project plugin setting.
84      bool enable;
85
86      /// "options" can be set to a list of ctags options. You may need to escape character "\".
87      vector< string > options;
88
89      /// "index_file" can be set to path of ctags file to generate.
90      /// A relative path is wrt to the project base directory.
91      string index_file;
92   }
93
94};
95
96
97
98Simple example, get files via globbing recursively in doc/, no build plugin:
99
100{
101   "name": "MyProject",
102   "files": [ {
103             "directory": "doc",
104             "filters": ["*.tex", "Makefile"],
105             "recursive": 1
106       } ]
107}
108
109
110A project for a custom language named Swine whose source files have a suffix .swn:
111
112{
113   "name": "Custom",
114   "files": [ {
115         "directory": ".",
116         "filters": ["*.swn"],
117         "recursive": 1
118      } ],
119   "ctags": {
120      "options": [
121         "--langdef=swine",
122         "--langmap=swine:.swn",
123         "--regex-swine=/^def[ \t]*([a-zA-Z0-9_]+)/\\1/d,definition/"
124      ]
125   }
126}
127
128
129A more advanced project file, get the files from svn, set up three commands for the build plugin:
130
131{
132   "name": "Foo",
133   "files": [ { "svn" : 1  } ],
134
135   "build": {
136      "directory": "build",
137      "build": "make all -j4",
138      "clean": "make clean",
139      "quick": "make install"
140  }
141}
142
143
144An out-of-source project file as generated by cmake: it points to the actual project directory,
145it retrieves the file list from git, and a long list of targets for the build plugin:
146
147
148{
149   "name": "CMake@build",
150   "directory": "/home/neundorf/src/CMake/cmake",
151   "files": [ { "git": 1 } ],
152   "build": {
153       "directory": "/home/neundorf/src/CMake/build",
154       "default_target": "all",
155       "clean_target": "clean",
156       "targets":[
157           { "name":"all", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build -j8 all" },
158           { "name":"clean", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build -j8 clean" },
159           { "name":"cmLocalGenerator.cxx.o", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmLocalGenerator.cxx.o" },
160           { "name":"cmLocalGenerator.cxx.i", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmLocalGenerator.cxx.i" },
161...
162           { "name":"cmLocalGenerator.cxx.s", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmLocalGenerator.cxx.s" },
163           { "name":"cmMakefile.cxx.o", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmMakefile.cxx.o" },
164           { "name":"cmMakefile.cxx.i", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmMakefile.cxx.i" },
165           { "name":"cmMakefile.cxx.s", "build_cmd":"/usr/bin/gmake -C /home/neundorf/src/CMake/build/Source -j8 cmMakefile.cxx.s" }
166       ] }
167}
168