.. -*- coding: utf-8 -*-

.. /** @file HowToBuildReadme.txt
      
     XBL build documentation
   
     Copyright (c) 2017 - 2018, 2023 Qualcomm Technologies Inc. All rights reserved. 
     
   **/
   
   /*=============================================================================
                                 EDIT HISTORY
   
   
    when       who     what, where, why
    --------   ---     -----------------------------------------------------------
    08/22/23   bxr     Update
    03/09/18   yg      Update
    05/10/17   yps     Initial version
   =============================================================================*/


.. _HowToBuildReadme:

================
HowToBuildReadme
================

Required Tool and Setup
-----------------------

Toolchain versions (common for both windows/linux)::

  - Python : 3.10.6  (required in search path, use "python -V" to verify)
   
For Windows::

  1) DTC: Install DTC from QPM. (Please join dtc.qpm.viewer for access permisson )
  
  2) Sectools V2: Recommand to copy \\sundae\sectools\v2 to local PC and export sectools path to os envoirnment variable SECTOOLS
  
  3) DTSchema: Extract \\jerry\corebsp_labdata_0002\DTSCHEMA_Windows_Tools\dtschematools.zip to C:\Apps\
  
  4) VisualStudio: Please install VS2010 or later version(It is only suppported until VS2019)
  
  5) Compiler: Extract \\skinnycow\fluid_home\release\16.0.7\Snapdragon-llvm-16.0.7-windows64.zip to C:\Apps\LLVM\16.0.7

Install iasl driver::

  linux: sudo apt-get install iasl
  Windows:
    1) Download/install iasl
    2) Rename downloaded folder to ASL
    3) Move it to C drive (C:/ASL/iasl.exe)
    4) Add C:/ASL/iasl in env variable path


Build Command and options
-------------------------

Windows/Linux::

  boot_tools\buildex.py
  This is the common build script for all packages

Build Options::

  Usage: python buildex.py [optional arguments]... 

Examples:
  
  python boot_tools/buildex.py

Arguments:

``-t --target``

  Provide target(s) to build, separated by a comma
  ex: python buildex.py -t Pakala

``--variant``

  Provide variant(s) to build, separated by a comma
  
  ex: python buildex.py --variant XX,YY
  
  where XX, YY are variant folders in a target package folder
  
``-r --release``
  
  Provide a release mode, one of "DEBUG" or "RELEASE". Default is to build both.

``-v --version``

  Specify build version. Default is 0.

``-a --alias``

  Specify the config section as listed in the file QcomPkg/aliasconfig.json to provide 
  the build params instead of manually specifying on command line

``-C --component``
  
  Will only compile the components which proivide with this option, separeted by a comma .


``--build_flags``

  Comma separated list of extra arguments to be supplied to the underlying build system (here EDK build system).
  
  ex: python buildex.py --build_flags cleanall,special

  Extra Build Arg options:
  
  These are comma separated values, within double quotes if space is needed, any valid combination of the
  values can be used::
  
    -v       : verbose
    -m file  : Module inf file to build (relative path from root of workspace)
    -n x     : Number of threads to spawn for the build (x = 1 when need to locate error)
    cleanall : Clean all the generated files
  
``--compiler_flags``

  This string is passed in its entirety to the compiler. Quotes may be used for strings
  that require a space.
  
  ex: python buildex.py --compiler_flags -DPRE_SIL
  
  ex: python buildex.py --compiler_flags "-DSOME_FLAG -DANOTHER_FLAG"
          
``-i --images``

  Provide image which you want to generate,separeted by a comma
  
  ex: python buildex.py -i xbl,uefi,pmic



Some usage Examples
-------------------

``python buildex.py -t Lanai --variant LAA -r DEBUG,RELEASE``

  Building a specific target, variant LAA for DEBUG and RELEASE

``python buildex.py -t Lanai --variant LAA -r DEBUG -i uefi``

  Building a specific target, variant, and single image uefi for DEBUG
  
``python buildex.py -t Lanai --variant LAA -r DEBUG -C XBL_CORE``
  
  Building a specific target 8250pkg, variant LAA and sepceial component XBL_CORE 
  for DEBUG

``python buildex.py -t Lanai --variant LAA -r debug --build_flags cleanall``
  
  Clean Lanai, LAA Debug image
  
``python buildex.py -a lndevclean -t lanai``

  Building a specific target lanai, variant LAA for DEBUG by alias 
  option. Detail option alias please refer aliasconfig.json
