summaryrefslogtreecommitdiffstats
path: root/doc/ref_parameter.rst
blob: f2ea2ae1865cd2002b065fe026e64c21b497df81 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
Setup and Project Actions
~~~~~~~~~~~~~~~~~~~~~~~~~

``menu``
  this starts a dialog based frontend for those who do not like typing
  commands. It will gain us access to the most common parameters to
  configure and build a PTXdist project. This menu handles the
  actions *menuconfig*, *platformconfig*, *kernelconfig*, *select*,
  *platform*, *boardsetup*, *setup*, *go* and *images*.

``select <config>``
  this action will select a user land
  configuration. This step is only required in projects, where no
  ``selected_ptxconfig`` file is present. The <config> argument must point
  to a valid user land configuration file. PTXdist provides this feature
  to enable the user to maintain more than one user land configuration in
  the same project. The default location for the configuration file is
  ``configs/ptxconfig``. PTXdist will use this if no other configuration is
  selected.

``platform <config>``
  this action will select a platform
  configuration. This step is only required in projects, where no
  ``selected_platform`` file is present. The <config> argument must point
  to a valid platform configuration file. PTXdist provides this feature to
  enable the user to maintain more than one platform in one project.
  The default location for the configuration file is
  ``configs/*/platformconfig``. PTXdist will use it if the pattern matches
  exactly one file and no other configuration is selected.

``toolchain [<path>]``
  this action will select the toolchain to use. If no path is specified
  then PTXdist will guess which toolchain to use based on the settings in
  the platformconfig. Setting the toolchain is only required if PTXdist
  cannot find the toolchain automatically or if a different toolchain
  should be used.

``collection <config>``
  this action will select a collection configuration. This step is
  optional. The <config> argument must point to a valid collection
  configuration file.

``setup``
  PTXdist uses some global settings, independent from the
  project it is working on. These settings belong to users preferences or
  simply some network settings to permit PTXdist to download required
  packages.

``boardsetup``
  PTXdist based projects can provide information to
  setup and configure the target automatically. This action let the user
  setup the environment specific settings like the network IP address and
  so on.

``projects``
  if the generic projects coming in a separate archive
  are installed, this actions lists the projects a user can clone for its
  own work.

``clone <from> <to>``
  this action clones an existing project from
  the ``projects`` list into a new directory. The <from>argument must be a
  name gotten from ``ptxdist projects`` command, the <to>argument is the
  new project (and directory) name, created in the current directory.

``menuconfig``
  start the menu to configure the project’s root
  filesystem. This is in respect to user land only. Its the main menu to
  select applications and libraries, the root filesystem of the target
  should consist of.

``menuconfig platform``
  this action starts the menu to configure
  platform’s settings. As these are architecture and target specific
  settings it configures the toolchain, the kernel and a bootloader (but
  no user land components). Due to a project can support more than one
  platform, this will configure the currently selected platform. The short
  form for this action is ``platformconfig``.

``menuconfig kernel``
  start the menu to configure the platform’s
  kernel. As a project can support more than one platform, this will
  configure the currently selected platform. The short form for this
  action is ``kernelconfig``.

``menuconfig barebox``
  this action starts the configure menu for
  the selected bootloader. It depends on the platform settings which
  bootloader is enabled and to be used as an argument to the
  ``menuconfig`` action parameter. Due to a project can support more than
  one platform, this will configure the bootloader of the currently
  selected platform.

``nconfig [<component>]``
  this action provides a slightly different user experience with the same
  functionality as ``menuconfig``. It can be used instead of ``menuconfig``
  for all the component described above.

``oldconfig [<component>]``, ``allmodconfig [<component>]``, ``allyesconfig [<component>]``, ``allnoconfig [<component>]``, ``randconfig [<component>]``
  this action will run the corresponding kconfig action for the specified
  component. ``oldconfig`` will prompt for all new options.
  ``allmodconfig``, ``allyesconfig`` and ``allnoconfig`` will set all
  options to 'm', 'y' or 'n' respectively. ``randconfig`` will randomize
  the options. The ``KCONFIG_ALLCONFIG`` and ``KCONFIG_SEED`` environment
  variables can be used as described in the Linux kernel documentation.

``migrate``
  migrate the configuration files from a previous PTXdist version. This
  will run ``oldconfig`` and ``oldconfig platform`` to prompt for all new
  options.

Build Actions
~~~~~~~~~~~~~

``go``
  this action will build all enabled packages in the current
  project configurations (platform and user land). It will also rebuild
  reconfigured packages if any or build additional packages if they where
  enabled meanwhile. If enables this step also builds the kernel and
  bootloader image.

``get <package>``, ``extract <package>``, ``prepare <package>``, ``compile <package>``, ``install <package>``, ``targetinstall <package>``
  this action will build the corresponding stage for the specified package
  including all previous stages and other dependencies. Multiple packages
  can be specified.

``drop <package>.<stage>``
  this action will 'drop' the specified stage without removing any other
  files. Subsequent actions will rebuild this stage. This is useful during
  development to rebuild a package without deleting the sources. Use
  ``clean <package>`` for a full rebuild of the package.

``images``
  most of the time this is the last step to get the
  required files and/or images for the target. It creates filesystems or
  device images to be used in conjunction with the target’s filesystem
  media. The result can be found in the ``images/`` directory of the
  project or the platform directory.

``image <image>``
  build the specified image. The file name in ``images/`` is used to
  identify the image. This is basically the same as ``images`` but builds
  just one image.

  Note: This is only supported for the images in the 'new image creation
  options' section of the platformconfig.

Clean Actions
~~~~~~~~~~~~~

``clean``
  the ``clean`` action will remove all generated files
  while the last ``go`` run: all build, packages and root filesystem
  directories. Only the selected configuration files are left untouched.
  This is a way to start a fresh build cycle.

``clean root``
  this action will only clean the root filesystem
  directories. All the build directories are left untouched. Using this
  action will re-generate all ipkg/opkg archives from the already built
  packages and also the root filesystem directories in the next ``go``
  action. The ``clean root`` and ``go`` action is useful, if the
  *targetinstall* stage for all packages should run again.

``clean <package>``
  this action will only clean the dedicated
  <package>. It will remove its build directory and all installed files
  from the corresponding sysroot directory. Multiple packages can be
  specified.

``distclean``
  the ``distclean`` action will remove all files that
  are not part of the main project. It removes all generated files and
  directories like the ``clean`` action and also the created links in any
  ``platform`` and/or ``select`` action.

Misc Actions
~~~~~~~~~~~~

``version``
  print out the PTXdist version.

``test <testname>``
  run tests

``newpackage <type>``
  create a new PTXdist package. For most package types, this will create
  <pkg>.make and <pkg>.in files in rules/. Use ``newpackage help`` for a
  list of available package types.

``nfsroot``
  run a userspace NFS server and export the nfsroot.

``print <var>``
  print the contents of a variable. It will first look for a shell variable
  with the given name. If none exists, it will run make and look if a
  variable with the given name is known to 'make'.

``list-packages``
  print a list of all selected packages. This list does not include the
  host and cross tools.

``local-src <pkg> [<directory>]``
  overwrite a package source with a locally provided directory containing
  the source code. Not specifying the directory will undo the change.

``bash``
  enter a PTXdist environment bash shell.

``bash <cmd> [args...]``
  execute ``<cmd>`` in PTXdist environment.

``make <target>``
  build specified make target in PTXdist.

``export_src <target-dir>``
  export all source archives needed for this project to ``<target-dir>``.

Overwrite defaults
~~~~~~~~~~~~~~~~~~

These options can be used to overwrite some settings. They can be useful
when working with multiple configurations or platforms in a single project.

``--ptxconfig=<config>``
  use the specified ptxconfig file instead of the selected of default
  configuration file.

``--platformconfig=<config>``
  use specified platformconfig file instead of the selected of default
  configuration file.

``--collectionconfig=<config>``
  use specified collectionconfig file instead of the selected configuration
  file.

``--toolchain=<toolchain>``
  use specified toolchain instead of the selected or default toolchain.

``--force-download``
  allow downloading, even if disabled by setup

Options
~~~~~~~

``--force``, ``-f``
  use this option to overwrite various sanity checks. Only use this option
  if you really know what you are doing.

``--debug``, ``-d``
  print out additional info (like make decisions)

``--quiet``, ``-q``
  suppress output, show only stderr

``--verbose``, ``-v``
  be more verbose, print command before execute them

``--output-sync``, ``--no-output-sync``
  enable or disable output synchronization. By default output
  synchronization is only enabled for quiet builds. Output synchronization
  is implemented by the ``make`` ``--output-sync`` option. For building
  packages in parallel, ``--output-sync=recurse`` is used. For individual
  ``make`` commands in the build stages ``--output-sync=target`` is used.
  This means, that the output for each individual make target and each
  build stage is grouped together.

  Note: If  output synchronization enabled then the output for each build
  stage is collected by make and won't be visible until the build stage is
  completed. As a result, there will be long periods of time with no
  visible progress.

``--j-intern=<n>``, ``-ji<n>``
  set number of parallel jobs within packages. PTXdist will use this
  number for example when calling ``make`` during the compile stage.
  The default is 2x the number of CPUs.

``--j-extern=<n>``, ``-je<n>``
  set number of packages built in parallel. The default is 1.
  Use ``-j`` instead of this. It has the same goal and performs better.

``-j[<n>]``
  set the global number of parallel jobs. This is basically a more
  intelligent combination of ``-je`` and ``-ji``. A single package rarely
  uses all the available CPUs. Usually only the compile can use more than
  one CPU and even then there are often idle CPUs. With the global job
  pool, tasks from multiple packages can be executed in parallel without
  overloading the system.

  Note: Because of the parallel execution, the output is chaotic and not
  very useful. Use this in combination with ``-q`` and only to speed up
  building for project that are known to build without errors.

``--load-average=<n>``, ``-l<n>``
  try to limit load to <n>. This is used for the equivalent ``make``
  option.

``--nice=<n>``, ``-n<n>``
  run with reduced scheduling priority (i.e. nice). The default is 10.

``--keep-going``, ``-k``
  keep going. Continue as much as possible after an error.

``--git``
  use git to apply patches

``--auto-version``
  automatically switch to the correct PTXdist version. This will look for
  the correct PTXdist version in the ptxconfig file and execute it if it
  does not match the current version.