/*
    cbp2make : Makefile generation tool for the Code::Blocks IDE
    Copyright (C) 2010-2013 Mirai Computing (mirai.computing@gmail.com)

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

/*!
  \file cbworkspace.h
  \brief Workspace unit and workspace descriptions.
*/

/*!
  \file cbworkspace.cpp
  \brief Workspace unit and workspace descriptions.
*/

/*!
  \class CWorkspaceUnit
  \brief Workspace unit description.

  Contains properties of Code::Blocks workspace:
  subprojects, their dependencies and priorities.
*/

/*!
  \var CWorkspaceUnit::m_FileName
  \brief Workspace unit file name.
*/

/*!
  \var CWorkspaceUnit::m_Depends
  \brief List of workspace unit dependencies.

  Contains list of other workspace unit (project) names that
  this workspace unit requires to be built before itself.
*/

/*!
  \var CWorkspaceUnit::m_Project
  \brief Contains project properties.

  \sa CCodeBlocksProject.
*/

/*!
  \var CWorkspaceUnit::m_Weight
  \brief Weight (priority) of the workspace unit.

  Normally workspace unit weights range from 0 to 100.
  Lower weight means higher priority and vice versa.
  Workspace units with lower weights are compiled and linked first.
*/

/* !
  \var CWorkspaceUnit::
  \brief .
*/

/*!
  \fn CWorkspaceUnit::Clear(void)
  \brief Resets the workspace unit to the initial state.
*/

/*!
  \fn CWorkspaceUnit::Read(const TiXmlElement* UnitRoot)
  \brief Reads the workspace unit settings from an XML document.
  \param UnitRoot an element of XML document.
*/

/*!
  \fn CWorkspaceUnit::Show(void)
  \brief Prints the workspace unit contents to standard output.
*/

/*!
  \fn CWorkspaceUnit::LoadProject(void)
  \brief Loads the workspace unit (project) from file.
  \return \a true if the workspace unit was successfully loaded, \a false otherwise.

  Uses CBuildProject::LoadProject(const CString& FileName)
  with CWorkspaceUnit::m_FileName as the workspace unit file name.
*/

/*!
  \fn CWorkspaceUnit::CWorkspaceUnit(void)
  \brief Creates workspace unit.
*/

/*!
  \fn CWorkspaceUnit::~CWorkspaceUnit(void)
  \brief Destroys workspace unit.
*/

/* !
  \fn CWorkspaceUnit::
  \brief .
  \param .
  \return .
*/

/*!
  \class CCodeBlocksWorkspace
  \brief Workspace description.

  Contains properties of Code::Blocks workspace.
*/

/*!
  \var CCodeBlocksWorkspace::m_Title
  \brief Title of the workspace.
*/

/*!
  \var CCodeBlocksWorkspace::m_Units
  \brief List of workspace units (projects) in the workspace.

  \sa CWorkspaceUnit.
*/

/*!
  \var CCodeBlocksWorkspace::m_TargetNames
  \brief List of build target names of workspace units.

  This list is automatically refreshed by
  CCodeBlocksWorkspace::GenerateMakefile(const CString& FileName, CCodeBlocksBuildConfig& Config).
*/

/*!
  \var CCodeBlocksWorkspace::m_MakefileNames
  \brief List of makefile names of workspace units.

  This list is automatically refreshed by
  CCodeBlocksWorkspace::GenerateMakefile(const CString& FileName, CCodeBlocksBuildConfig& Config).
*/

/*!
  \var CCodeBlocksWorkspace::m_MakefilePaths
  \brief List of makefile paths of workspace units.

  This list is automatically refreshed by
  CCodeBlocksWorkspace::GenerateMakefile(const CString& FileName, CCodeBlocksBuildConfig& Config).
*/

/*!
  \var CCodeBlocksWorkspace::m_TargetDeps
  \brief List of dependencies of workspace units.

  Each line of the list contains decorated project names separated by space character
  and represents dependencies of corresponding project contained in the workspace.
  Decorated names are used as makefile target names. This list is automatically refreshed by
  CCodeBlocksWorkspace::GenerateMakefile(const CString& FileName, CCodeBlocksBuildConfig& Config).
*/

/*!
  \var CCodeBlocksWorkspace::m_MakefileText
  \brief Contains plain text of makefile for the workspace.

  Contents of makefile are generated by
  CCodeBlocksWorkspace::GenerateMakefileText(const CString& FileName, CCodeBlocksBuildConfig& Config)
  before saving to a file.
*/

/*!
  \var CCodeBlocksWorkspace::m_Makefile
  \brief Contains object-based makefile for the workspace.

  Contents of makefile are generated by
  CCodeBlocksWorkspace::GenerateMakefile(const CString& FileName, CCodeBlocksBuildConfig& Config)
  before saving to a file.
*/

/* !
  \var CCodeBlocksWorkspace::
  \brief .
*/

/*!
  \fn CCodeBlocksWorkspace::CalculateProjectWeight(const size_t Index = 0)
  \brief Calculates weight (priority) of a single workspace unit (project) with number \a Index.
  \param Index number of a workspace unit (project).
  \return weight of a project.

  This function is a part of the core mechanism for resolving project dependencies.
  \sa CCodeBlocksWorkspace::ResolveProjectDependencies(void)
*/

/*!
  \fn CCodeBlocksWorkspace::ResolveProjectDependencies(void)
  \brief Resolves workspace unit (project) dependencies by calculating project weights.

  \sa CCodeBlocksWorkspace::CalculateProjectWeight(const size_t Index = 0)
*/

/*!
  \fn CCodeBlocksWorkspace::SortProjectsByWeight(void)
  \brief Sorts workspace units (projects) by weight in ascending order.

  This function is a part of the core mechanism for resolving project dependencies.
  \sa CCodeBlocksWorkspace::ResolveProjectDependencies(void)
*/

/*!
  \fn CCodeBlocksWorkspace::Clear(void)
  \brief Resets the workspace to the initial state.
*/

/*!
  \fn CCodeBlocksWorkspace::Read(const TiXmlElement* WorkspaceRoot)
  \brief Reads the workspace settings from an XML document.
  \param WorkspaceRoot an element of XML document.
*/

/*!
  \fn CCodeBlocksWorkspace::LoadWorkspaceProjects(void)
  \brief Loads all workspace units (projects) in the workspace.
  \return \a true if all of projects were successfully loaded, \a false otherwise.
*/

/*!
  \fn CCodeBlocksWorkspace::LoadWorkspace(const CString& FileName)
  \brief Loads a workspace from a file specified by \a FileName.
  \param FileName name of Code::Blocks workspace file.
  \return \a true if specified workspace and all of its units (projects)
  were successfully loaded, \a false otherwise.
*/

/*!
  \fn CCodeBlocksWorkspace::Show(const bool ShowProjects = false)
  \brief Prints the workspace contents and (optionally) contents of workspace units (projects) to standard output.
  \param ShowProjects tell to display contents of workspace units.
*/

/*!
  \fn CCodeBlocksWorkspace::GenerateMakefile(const CString& FileName, CCodeBlocksBuildConfig& Config)
  \brief Generates makefile and writes its text representation to a file specified by \a FileName.
  \param FileName a file name for makefile  of the workspace.

  \param Config build configuration.

  This function generates makefile text only for the workspace,
  makefiles for individual projects in the workspace are generated by CCodeBlocksProject.
*/

/*!
  \fn CCodeBlocksWorkspace::GenerateMakefileText(const CString& FileName, CCodeBlocksBuildConfig& Config)
  \brief Generates makefile text and writes it to a file specified by \a FileName.
  \param FileName a file name for makefile of the workspace.

  \param Config build configuration.

  This function generates makefile text only for the workspace,
  makefiles for individual projects in the workspace are generated by CCodeBlocksProject.
*/

/*!
  \fn CCodeBlocksWorkspace::CCodeBlocksWorkspace(void)
  \brief Create workspace.
*/

/*!
  \fn CCodeBlocksWorkspace::~CCodeBlocksWorkspace(void)
  \brief Destroys workspace.
*/

/* !
  \fn CCodeBlocksWorkspace::
  \brief .
  \param .
  \return .
*/

//------------------------------------------------------------------------------
