/*
 * Copyright 2003-2017 JetBrains s.r.o.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package jetbrains.mps.project.facets;

import jetbrains.mps.vfs.IFile;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import org.jetbrains.mps.openapi.model.SModel;
import org.jetbrains.mps.openapi.module.SModuleFacet;

/**
 * PROVISIONAL API, DO NOT USE OUTSIDE OF MPS.
 * Facet for a module that is capable of producing file artifacts, e.g. source code, configuration files, images.
 * It's distinct from {@link JavaModuleFacet} which knows about class files and classpath, while this one doesn't imply generated artifacts need any
 * special treatment.
 *
 * FIXME what about make scenario, with output location re-defined? Perhaps, facet shall tell relative location only (Path instead of IFile), while Make
 *       determines placement. What about module compile then? How would it take base path?
 * <p/>
 *
 * DESIGN NOTE: With location-agnostic modules, might be fruitful to express locations as relative Path, not IFile objects. It's common to collect module's
 *              output paths just to match paths of generated files and to re-target them to different location (see {@code ModuleOutputPaths}).
 *              OTOH, relative to what?
 * <p/>
 * Single module may instantiate multiple {@code GenerationTargetFacet} instances to target multiple generation objectives.
 * It's up to specific facet to tell e.g. Make process which compiler/processor to use.
 *
 * TODO Perhaps, Make process may pick appropriate {@code GenerationTargetFacet} based on {@link SModuleFacet#getFacetType() facet type}
 *      (e.g. GTFSupplier.getSourceGenerationFacet(SModel):GTF. SModel may keep facet type as its property.
 * @author Artem Tikhomirov
 * @since 3.5
 */
public interface GenerationTargetFacet extends SModuleFacet {
  /**
   * Location for output files.
   * Generally, shall not be nullable, but would like to give implementors freedom to imply own restrictions (and it's safer to override with
   * NotNull than vice versa).
   * @param model model of a module this facet is associated with
   * @return FS location where generated files for the model go (not necessarily identical for the model, models may share one, unless otherwise node by implementation)
   */
  @Nullable
  IFile getOutputLocation(@NotNull SModel model);

  /**
   * Facilitates keeping related generated artifacts, e.g. descriptor, index, debug-related information, which is auxiliary to primary generation
   * artifacts residing in {@link #getOutputLocation(SModel)}
   * @param model model of a module this facet is associated with
   * @return FS location for auxiliary generated files
   */
  @Nullable
  IFile getOutputCacheLocation(@NotNull SModel model);
}